@hivey/cli 0.9.50 → 0.9.51

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.
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hivey/cli",
3
- "version": "0.9.50",
3
+ "version": "0.9.51",
4
4
  "description": "All your AI swarms, one terminal: a workspace and lead agent for teams of Claude Code and Codex agents",
5
5
  "keywords": [
6
6
  "hivey",
@@ -110,6 +110,17 @@ hivey agent-map schedule install [--at 06:30] [--model haiku] # | remove | sta
110
110
 
111
111
  - **hivey menu → agent map** runs `hivey agent-map open`: it opens `agent-stats.html`,
112
112
  `agent-map.html` and `agent-logs.html` from `~/.hivey/agent-map/reports/latest`.
113
+ - **hivey's layer on the archify pages** (`enhance.py`, after finalize; `agent_map.py enhance [folder]`
114
+ re-applies it): a Stats · Map · Logs navbar on every page; map boxes coloured by spend (green: none →
115
+ red: the most, log scale, with a legend); a hover explanation on each column header; and in each box's
116
+ info card what it does, spend, tokens, calls, models and last run. Boxes are tied to snapshot nodes by
117
+ `map-meta.json` (`{"nodes": {"<box id>": {"refs": [...], "description": "…"}}, "stages": {...}}`,
118
+ written by the nightly model), else by label. A job counts only its own spend, not its agent's.
119
+ - **Descriptions** ("what it does"): from a brief's mission, a skill's description or a script's module
120
+ docstring; the nightly model writes the missing or weak ones to `~/.hivey/agent-map/descriptions.json`
121
+ (kept, edit freely), which wins over the extracted ones. They show in the map's info cards and the run log.
122
+ - **Per day:** the stats page charts the top agents' cost per day and lists each day's cost, tokens and
123
+ top agents (`usage.daily_by_agent` in the snapshot).
113
124
  - **`agent-logs.html`** (run log, written by code): every scheduled job with ✅ ran ok · ⚠️ errors in
114
125
  its log or a missed run (a launchd log older than its schedule allows) · ❌ non-zero exit or not
115
126
  loaded · ⏳ running · ❔ no log, its last run, the issue, and on click the error lines and last 40
@@ -451,6 +451,15 @@ class Usage:
451
451
  agents.append({"agent": name, "last_active": seen.astimezone().isoformat(timespec="minutes") if seen else None,
452
452
  **{k: round(v, 4) if isinstance(v, float) else v for k, v in tot.items()},
453
453
  "models": [m for m, _ in models.most_common()], "providers": [p for p, _ in providers.most_common()]})
454
+ day_agent = collections.defaultdict(lambda: collections.defaultdict(blank))
455
+ for r in self.rows:
456
+ acc = day_agent[r[0]][r[1]]
457
+ for k, v in r[5].items():
458
+ acc[k] += v
459
+ daily_agents = {day: sorted(({"agent": a, "cost_usd": round(v["cost_usd"], 4), "calls": v["calls"],
460
+ "tokens": v["input"] + v["output"] + v["cache_read"] + v["cache_write"]}
461
+ for a, v in per.items()), key=lambda x: -x["cost_usd"])
462
+ for day, per in sorted(day_agent.items())}
454
463
  daily = collections.defaultdict(dict)
455
464
  for (day, prov), tot in group(lambda r: (r[0], r[2])).items():
456
465
  daily[day][prov] = round(tot["cost_usd"], 4)
@@ -462,12 +471,113 @@ class Usage:
462
471
  for k, v in group(lambda r: r[3]).items()},
463
472
  "kinds": {k: round(v["cost_usd"], 4) for k, v in group(lambda r: r[4]).items()},
464
473
  "daily_cost_by_provider": dict(sorted(daily.items())),
474
+ "daily_by_agent": daily_agents,
465
475
  "total_cost_usd": round(sum(r[5]["cost_usd"] for r in self.rows), 2),
466
476
  "total_tokens": sum(r[5]["input"] + r[5]["output"] + r[5]["cache_read"] + r[5]["cache_write"] for r in self.rows),
467
477
  "sources_without_tokens": ["antigravity (agy): no per-session token data on disk"],
468
478
  }
469
479
 
470
480
 
481
+ # ---------------------------------------------------------------- descriptions
482
+
483
+ DESCRIPTIONS = STATE / "descriptions.json" # {node id: "what it does"}: written by the nightly model or you
484
+
485
+
486
+ def first_sentence(text: str, limit: int = 170) -> str:
487
+ text = re.sub(r"`|\*\*|__|\[([^\]]*)\]\([^)]*\)", lambda m: m.group(1) or "", text)
488
+ text = " ".join(text.split())
489
+ m = re.match(r"(.+?[.!?])(\s|$)", text)
490
+ out = m.group(1) if m else text
491
+ return out if len(out) <= limit else out[: limit - 1].rsplit(" ", 1)[0] + "…"
492
+
493
+
494
+ def describe_markdown(path: Path) -> str:
495
+ """A brief's mission (or its first real paragraph), or a SKILL.md description."""
496
+ try:
497
+ text = path.read_text(errors="replace")
498
+ except OSError:
499
+ return ""
500
+ fm = re.match(r"---\n(.*?)\n---", text, re.S)
501
+ if fm:
502
+ m = re.search(r"^description:\s*\"?(.+?)\"?\s*$", fm.group(1), re.M)
503
+ if m:
504
+ return first_sentence(m.group(1))
505
+ text = text[fm.end():]
506
+ text = re.sub(r"<!-- BEGIN (GUIDELINES|GLOBAL[^>]*)-->.*?<!-- END (GUIDELINES|GLOBAL)[^>]*-->", "", text, flags=re.S)
507
+ text = re.sub(r"^# General guidelines.*?(?=^# (?!General))", "", text, flags=re.S | re.M)
508
+ m = re.search(r"^#{1,3}\s*(your mission|mission|purpose|what (this|it) does)\b.*?\n(.+?)(\n#|\Z)",
509
+ text, re.I | re.M | re.S)
510
+ body = m.group(3) if m else text
511
+ if BOILERPLATE.search(body[:300]) and m is None:
512
+ return "" # only the global guidelines: nothing about this agent
513
+ for para in re.split(r"\n\s*\n", body):
514
+ p = re.sub(r"^\s*(\d+\.|[-*])\s+", "", para.strip()) # a mission written as a list: its first item
515
+ if p and not p.startswith(("#", ">", "<!--", "|", "```")) and len(p) > 25 and not BOILERPLATE.search(p):
516
+ return first_sentence(p.split("\n")[0] if re.match(r"\s*(\d+\.|[-*])\s", para) else p)
517
+ return ""
518
+
519
+
520
+ BOILERPLATE = re.compile(r"behavioral guidelines|general guidelines|think before coding|you are claude|"
521
+ r"before implementing|state your assumptions|always end your final response|"
522
+ r"^(you are|i am) (the )?[\w -]{1,30}( agent)?\.?$|"
523
+ r"the user's (original )?request, verbatim|the user's words", re.I)
524
+
525
+
526
+ def describe_script(path: Path) -> str:
527
+ """The module docstring or leading comment block of a script (not a function's docstring)."""
528
+ try:
529
+ lines = path.read_text(errors="replace")[:6000].splitlines()
530
+ except OSError:
531
+ return ""
532
+ i, comments = 0, []
533
+ while i < len(lines):
534
+ l = lines[i].strip()
535
+ if l.startswith("#!") or l.startswith("# ///") or (comments == [] and re.match(r"#\s*(requires-python|dependencies|\]|\[|\")", l)):
536
+ i += 1
537
+ continue
538
+ if l.startswith("#"):
539
+ text = l.lstrip("# ").strip()
540
+ if text and not text.startswith(("-*-", "///", "noqa")):
541
+ comments.append(text)
542
+ i += 1
543
+ continue
544
+ if not l:
545
+ i += 1
546
+ if comments:
547
+ break
548
+ continue
549
+ break
550
+ if i < len(lines) and re.match(r'^[rub]*("""|\'\'\')', lines[i].strip()):
551
+ q = lines[i].strip().lstrip("rub")[:3]
552
+ body = [lines[i].strip()[len(q) + (len(lines[i].strip()) - len(lines[i].strip().lstrip("rub"))):]]
553
+ j = i + 1
554
+ while j < len(lines) and q not in body[-1]:
555
+ body.append(lines[j].strip())
556
+ j += 1
557
+ text = " ".join(body).split(q)[0]
558
+ para = re.split(r"\s{2,}|\n\s*\n", text.strip())[0]
559
+ if para and not BOILERPLATE.search(para):
560
+ return first_sentence(para)
561
+ joined = " ".join(comments)
562
+ return first_sentence(joined) if len(joined) > 20 and not BOILERPLATE.search(joined) else ""
563
+
564
+
565
+ def describe_job(j: dict) -> str:
566
+ for p in job_run_files(j["command"]):
567
+ pp = Path(p)
568
+ if pp.parent.name == "scripts" and (pp.parent.parent / "SKILL.md").is_file():
569
+ d = describe_markdown(pp.parent.parent / "SKILL.md")
570
+ if d:
571
+ return d
572
+ d = describe_script(pp)
573
+ if d:
574
+ return d
575
+ m = re.search(r'claude\b.*?-p\s+["\']/([\w-]+)', j["command"])
576
+ if m and (HOME / ".claude/skills" / m.group(1) / "SKILL.md").is_file():
577
+ return describe_markdown(HOME / ".claude/skills" / m.group(1) / "SKILL.md")
578
+ return ""
579
+
580
+
471
581
  # ---------------------------------------------------------------- links
472
582
 
473
583
  TABLE_RES = [
@@ -655,6 +765,18 @@ def scan(days: int) -> dict:
655
765
  live = live_agents()
656
766
  usage = Usage(days).collect().summary()
657
767
  nodes, candidates = build_links(jobs, live)
768
+ overrides = load_json(DESCRIPTIONS, {})
769
+ for j in jobs:
770
+ j["description"] = overrides.get(j["id"]) or describe_job(j)
771
+ by_job = {j["id"]: j["description"] for j in jobs}
772
+ for n in nodes:
773
+ if n["id"] in overrides:
774
+ n["description"] = overrides[n["id"]]
775
+ elif n["type"] == "job":
776
+ n["description"] = by_job.get(n["id"], "")
777
+ elif n.get("dir"):
778
+ n["description"] = next((d for d in (describe_markdown(Path(n["dir"]) / f) for f in
779
+ ("CLAUDE.md", "AGENTS.md", "README.md")) if d), "")
658
780
  for n in nodes:
659
781
  n.pop("paths", None)
660
782
  n.pop("run", None)
@@ -745,6 +867,8 @@ def main() -> int:
745
867
  nt.add_argument("--model", default="haiku")
746
868
  nt.add_argument("--no-llm", action="store_true", help="no model run: last night's map, unchanged")
747
869
  nt.add_argument("--open", action="store_true", help="open the report when done")
870
+ en = sub.add_parser("enhance", help="re-apply hivey's layer (navbar, colours, info) to a report")
871
+ en.add_argument("folder", nargs="?", default=str(STATE / "reports" / "latest"))
748
872
  op = sub.add_parser("open", help="open the latest report (builds the first one if there is none)")
749
873
  op.add_argument("--model", default="haiku")
750
874
  sc = sub.add_parser("schedule", help="the nightly launchd run: install | remove | status")
@@ -776,6 +900,12 @@ def main() -> int:
776
900
  if a.open:
777
901
  report.open_latest(a.model)
778
902
  return code
903
+ if a.cmd == "enhance":
904
+ import report, enhance
905
+ folder = Path(a.folder).expanduser().resolve()
906
+ enhance.enhance_folder(folder, json.loads((folder / "snapshot.json").read_text()), report.job_state)
907
+ print(f"enhanced {folder}")
908
+ return 0
779
909
  if a.cmd == "open":
780
910
  import report
781
911
  return report.open_latest(a.model)
@@ -0,0 +1,222 @@
1
+ """hivey's layer on top of the archify pages, added after they are finalized:
2
+
3
+ - a navbar (Stats · Map · Logs) on every page, so each page reaches the others;
4
+ - on the map: each job/agent box coloured by its spend in the window (green: none, red: the most),
5
+ with a legend; a hover explanation on each column header; and, in the box's info card, what the
6
+ job or agent does, its tokens, cost, calls, models and last run.
7
+
8
+ Map boxes are tied to the snapshot by `map-meta.json` in the report folder
9
+ ({"nodes": {"<map node id>": {"refs": ["agent:x-content", "cron:x-ai-agents-trends"],
10
+ "description": "…"}}, "stages": {"<stage label>": "…"}}), written by the nightly model; a box
11
+ without refs is matched by its label. Python standard library only.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import html
16
+ import json
17
+ import math
18
+ import re
19
+ from pathlib import Path
20
+
21
+ STAGE_HELP = {
22
+ "scheduled jobs": "Jobs that start on their own at set times (cron or launchd), without anyone asking.",
23
+ "raw data": "What the jobs write: transcripts, Baserow tables, files. Other jobs and agents read them.",
24
+ "pipelines": "Jobs that read the raw data and turn it into something: wiki pages, reports, summaries.",
25
+ "knowledge & agents": "Wikis and vaults the pipelines keep up to date, and the agents that feed others.",
26
+ "knowledge": "Wikis and vaults the pipelines keep up to date.",
27
+ "agents": "hivey agents you talk to: they read the knowledge and data on the left and do the work.",
28
+ "outputs": "What leaves the system: posts, messages, published files.",
29
+ }
30
+
31
+ NAV_CSS = """
32
+ .hv-nav{position:relative;z-index:50;display:flex;gap:4px;align-items:center;justify-content:center;
33
+ padding:6px 10px;font:600 13px/1.2 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
34
+ border-bottom:1px solid rgba(127,127,127,.25);background:rgba(127,127,127,.06)}
35
+ .hv-nav a{color:inherit;opacity:.65;text-decoration:none;padding:4px 12px;border-radius:999px}
36
+ .hv-nav a:hover{opacity:1;background:rgba(127,127,127,.14)}
37
+ .hv-nav a.on{opacity:1;background:rgba(47,111,236,.16);color:#2f6fec}
38
+ .hv-nav .hv-when{margin-left:12px;opacity:.5;font-weight:400;font-size:12px}
39
+ """
40
+
41
+ MAP_CSS = """
42
+ .hv-legend{position:fixed;left:14px;bottom:14px;z-index:40;padding:8px 10px;border-radius:10px;
43
+ font:12px/1.3 -apple-system,BlinkMacSystemFont,sans-serif;background:rgba(255,255,255,.92);color:#1d2330;
44
+ border:1px solid rgba(127,127,127,.3);box-shadow:0 2px 10px rgba(0,0,0,.08)}
45
+ html[data-theme="dark"] .hv-legend{background:rgba(22,27,34,.92);color:#e6edf3}
46
+ @media (prefers-color-scheme:dark){html:not([data-theme="light"]) .hv-legend{background:rgba(22,27,34,.92);color:#e6edf3}}
47
+ .hv-legend .bar{width:180px;height:9px;border-radius:5px;margin:5px 0 3px;
48
+ background:linear-gradient(90deg,hsl(120,65%,45%),hsl(60,75%,48%),hsl(0,70%,50%))}
49
+ .hv-legend .ends{display:flex;justify-content:space-between;opacity:.75}
50
+ .hv-info{margin-top:.7rem;padding-top:.6rem;border-top:1px solid rgba(127,127,127,.25);font-size:.78rem;line-height:1.45}
51
+ .hv-info .hv-desc{margin:0 0 .5rem;font-size:.85rem}
52
+ .hv-info dl{display:grid;grid-template-columns:auto 1fr;gap:.18rem .7rem;margin:0}
53
+ .hv-info dt{opacity:.6}.hv-info dd{margin:0;font-variant-numeric:tabular-nums}
54
+ .hv-info .hv-models{display:flex;flex-wrap:wrap;gap:.25rem}
55
+ .hv-info .hv-models span{padding:.05rem .4rem;border:1px solid rgba(127,127,127,.35);border-radius:999px;font-size:.7rem}
56
+ svg text.hv-stage{cursor:help;text-decoration:underline dotted;text-underline-offset:2px}
57
+ """
58
+
59
+
60
+ def nav(active: str, generated: str) -> str:
61
+ links = [("agent-stats.html", "Stats"), ("agent-map.html", "Map"), ("agent-logs.html", "Logs")]
62
+ items = "".join(f'<a href="{href}"{" class=on" if href == active else ""}>{label}</a>' for href, label in links)
63
+ return f'<nav class="hv-nav">{items}<span class="hv-when">scan {html.escape(generated[:16].replace("T", " "))}</span></nav>'
64
+
65
+
66
+ def inject(page: str, css: str, top: str, script: str = "") -> str:
67
+ """Adds hivey's pieces, each wrapped in <!--hv--> markers so a rerun replaces them."""
68
+ page = re.sub(r"<!--hv-->.*?<!--/hv-->", "", page, flags=re.S)
69
+ page = page.replace("</head>", f"<!--hv--><style>{css}</style><!--/hv--></head>", 1)
70
+ m = re.search(r"<body[^>]*>", page)
71
+ if m:
72
+ page = page[: m.end()] + f"<!--hv-->{top}<!--/hv-->" + page[m.end():]
73
+ if script:
74
+ block = f"<!--hv--><script>{script}</script><!--/hv-->"
75
+ page = page.replace("</body>", block + "</body>", 1) if "</body>" in page else page + block
76
+ return page
77
+
78
+
79
+ def money(v: float) -> str:
80
+ return f"${v:,.2f}"
81
+
82
+
83
+ def mtok(n: int) -> str:
84
+ return f"{n / 1e6:,.1f}M" if n >= 1e6 else f"{n / 1e3:,.0f}k" if n >= 1e3 else str(n)
85
+
86
+
87
+ def model_name(m: str) -> str:
88
+ m = m.rsplit("/", 1)[-1]
89
+ k = re.match(r"claude-(opus|sonnet|haiku)-(\d+)(?:-(\d{1,2}))?(?!\d)", m)
90
+ return (f"{k.group(1).title()} {k.group(2)}" + (f".{k.group(3)}" if k.group(3) else "")) if k else m
91
+
92
+
93
+ def node_data(snap: dict, spec: dict, meta: dict, job_state) -> dict:
94
+ usage = {a["agent"]: a for a in snap["usage"]["agents"]}
95
+ try: # what the nightly model (or you) wrote since the scan wins
96
+ overrides = json.loads((Path.home() / ".hivey/agent-map/descriptions.json").read_text())
97
+ except (OSError, ValueError):
98
+ overrides = {}
99
+ jobs = {j["id"]: j for j in snap["jobs"]}
100
+ jobs_by_name = {j["name"]: j for j in snap["jobs"]}
101
+ snodes = {n["id"]: n for n in snap["nodes"]}
102
+ snodes_by_label = {n["label"]: n for n in snap["nodes"]}
103
+ live = {}
104
+ for a in snap["live_agents"]:
105
+ live.setdefault(a["agent"], a)
106
+ out = {}
107
+ for n in spec.get("nodes", []):
108
+ m = (meta.get("nodes") or {}).get(n["id"], {})
109
+ refs = list(m.get("refs") or [])
110
+ if not refs:
111
+ label = n["label"]
112
+ for cand in (label, re.sub(r"\s+(vault|wiki|jobs?|agent)$", "", label)):
113
+ if cand in snodes_by_label:
114
+ refs.append(snodes_by_label[cand]["id"])
115
+ break
116
+ if cand in jobs_by_name:
117
+ refs.append(jobs_by_name[cand]["id"])
118
+ break
119
+ names, desc, states = [], m.get("description", ""), []
120
+ for ref in refs:
121
+ if overrides.get(ref) and not desc:
122
+ desc = overrides[ref]
123
+ j = jobs.get(ref)
124
+ if j:
125
+ # its own spend only: a job inside an agent's folder must not take the agent's cost
126
+ agent = j.get("agent") or ""
127
+ names += [j["name"]] + ([agent, agent.removeprefix("skill:")] if agent.startswith("skill:") else [])
128
+ desc = desc or j.get("description", "")
129
+ emo, words = job_state(j)
130
+ states.append(f"{emo} {words} · {(j.get('last_run') or j.get('log_modified') or '?').replace('T', ' ')}")
131
+ sn = snodes.get(ref)
132
+ if sn:
133
+ names.append(sn["label"])
134
+ desc = desc or sn.get("description", "")
135
+ if sn["type"] == "agent" and sn["label"] in live:
136
+ states.append(f"{live[sn['label']]['status']} in hivey")
137
+ seen, tot, models = set(), {"cost": 0.0, "tokens": 0, "out": 0, "calls": 0}, []
138
+ for name in names:
139
+ if name and name in usage and name not in seen:
140
+ seen.add(name)
141
+ a = usage[name]
142
+ tot["cost"] += a["cost_usd"]
143
+ tot["tokens"] += a["input"] + a["output"] + a["cache_read"] + a["cache_write"]
144
+ tot["out"] += a["output"]
145
+ tot["calls"] += a["calls"]
146
+ models += [model_name(x) for x in a["models"] if model_name(x) not in models]
147
+ out[n["id"]] = {"refs": refs, "desc": desc, "cost": round(tot["cost"], 2), "tokens": tot["tokens"],
148
+ "out": tot["out"], "calls": tot["calls"], "models": models[:4], "states": states[:3],
149
+ "subject": bool(refs) and n.get("type") != "database"}
150
+ spend = [d["cost"] for d in out.values() if d["subject"]]
151
+ top = max(spend, default=0.0)
152
+ for d in out.values():
153
+ if d["subject"]:
154
+ t = math.log1p(d["cost"]) / math.log1p(top) if top > 0 else 0.0
155
+ d["hue"] = round(120 * (1 - t))
156
+ return out, top
157
+
158
+
159
+ MAP_JS = r"""
160
+ (function(){
161
+ const D=__DATA__, STAGES=__STAGES__, DAYS=__DAYS__;
162
+ const fmt=v=>'$'+v.toLocaleString(undefined,{minimumFractionDigits:2,maximumFractionDigits:2});
163
+ const tok=n=>n>=1e6?(n/1e6).toFixed(1)+'M':n>=1e3?Math.round(n/1e3)+'k':String(n);
164
+ const esc=s=>String(s).replace(/[&<>"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
165
+ document.querySelectorAll('g[data-node-id]').forEach(g=>{
166
+ const d=D[g.dataset.nodeId]; if(!d) return;
167
+ if(d.hue!=null){g.querySelectorAll(':scope > rect:not(.c-mask)').forEach(r=>{
168
+ r.style.fill='hsla('+d.hue+',75%,50%,.18)'; r.style.stroke='hsl('+d.hue+',68%,42%)';});}
169
+ const t=g.querySelector(':scope > title');
170
+ if(t){t.textContent=[g.dataset.nodeLabel, d.desc, d.subject?(fmt(d.cost)+' in '+DAYS+' days · '+tok(d.tokens)+' tokens'+(d.models.length?' · '+d.models.join(', '):'')):''].filter(Boolean).join('\n');}
171
+ });
172
+ document.querySelectorAll('svg text').forEach(t=>{
173
+ const m=/^\s*\d+\s*\/\s*(.+?)\s*$/.exec(t.textContent||''); if(!m) return;
174
+ const help=STAGES[m[1].toLowerCase()]; if(!help) return;
175
+ t.classList.add('hv-stage');
176
+ const ti=document.createElementNS('http://www.w3.org/2000/svg','title'); ti.textContent=m[1]+': '+help; t.appendChild(ti);
177
+ t.style.pointerEvents='auto';
178
+ });
179
+ let current=null;
180
+ const pick=e=>{const g=e.target.closest&&e.target.closest('g[data-node-id]'); if(g) current=g.dataset.nodeId;};
181
+ document.addEventListener('pointerdown',pick,true); document.addEventListener('focusin',pick,true);
182
+ function fill(meta){
183
+ const box=meta.parentElement; if(!box||box.querySelector('.hv-info')) return;
184
+ const d=D[current]; if(!d) return;
185
+ const rows=[];
186
+ if(d.subject){
187
+ rows.push(['Spend', fmt(d.cost)+' in '+DAYS+' days (API-equivalent)']);
188
+ rows.push(['Tokens', tok(d.tokens)+' ('+tok(d.out)+' output) · '+d.calls.toLocaleString()+' calls']);
189
+ rows.push(['Models', d.models.length?'<span class="hv-models">'+d.models.map(m=>'<span>'+esc(m)+'</span>').join('')+'</span>':'no LLM calls recorded']);
190
+ }
191
+ d.states.forEach(s=>rows.push(['Last run', esc(s)]));
192
+ const div=document.createElement('div'); div.className='hv-info';
193
+ div.innerHTML=(d.desc?'<p class="hv-desc">'+esc(d.desc)+'</p>':'')+(rows.length?'<dl>'+rows.map(r=>'<dt>'+r[0]+'</dt><dd>'+r[1]+'</dd>').join('')+'</dl>':'');
194
+ meta.insertAdjacentElement('afterend',div);
195
+ }
196
+ new MutationObserver(()=>document.querySelectorAll('.semantic-passport-meta').forEach(fill))
197
+ .observe(document.body,{childList:true,subtree:true});
198
+ })();
199
+ """
200
+
201
+
202
+ def enhance_folder(folder: Path, snap: dict, job_state) -> None:
203
+ generated = snap.get("generated", "")
204
+ stats = folder / "agent-stats.html"
205
+ if stats.is_file():
206
+ stats.write_text(inject(stats.read_text(), NAV_CSS, nav("agent-stats.html", generated)))
207
+ page, spec_path = folder / "agent-map.html", folder / "map.json"
208
+ if page.is_file() and spec_path.is_file():
209
+ spec = json.loads(spec_path.read_text())
210
+ try:
211
+ meta = json.loads((folder / "map-meta.json").read_text())
212
+ except (OSError, ValueError):
213
+ meta = {}
214
+ data, top = node_data(snap, spec, meta, job_state)
215
+ stages = dict(STAGE_HELP)
216
+ stages.update({k.lower(): v for k, v in (meta.get("stages") or {}).items()})
217
+ script = (MAP_JS.replace("__DATA__", json.dumps(data)).replace("__STAGES__", json.dumps(stages))
218
+ .replace("__DAYS__", json.dumps(snap.get("window_days", 7))))
219
+ legend = (f'<div class="hv-legend"><b>Spend, last {snap.get("window_days", 7)} days</b><div class="bar"></div>'
220
+ f'<div class="ends"><span>$0</span><span>{money(top)}</span></div>'
221
+ f'<div style="opacity:.65;margin-top:3px">click a box for what it does, tokens and models</div></div>')
222
+ page.write_text(inject(page.read_text(), NAV_CSS + MAP_CSS, nav("agent-map.html", generated) + legend, script))
@@ -160,6 +160,30 @@ def write_stats(snap: dict, folder: Path) -> None:
160
160
  L.append("## How does the cost move day by day? {#daily}\n")
161
161
  L.append('@chart type=line data=daily.csv x=day y=cost_usd unit=USD title="Daily cost, all providers '
162
162
  '(API-equivalent USD, estimated; today is partial)"\n')
163
+ per_day = u.get("daily_by_agent", {})
164
+ if per_day:
165
+ top5 = [a["agent"] for a in agents[:5]]
166
+ cols = [re.sub(r"[^\w-]", "_", a) for a in top5]
167
+ with open(folder / "daily_agents.csv", "w", newline="") as fh:
168
+ w = csv.writer(fh)
169
+ w.writerow(["day"] + cols)
170
+ for day, rows in per_day.items():
171
+ by = {r["agent"]: r["cost_usd"] for r in rows}
172
+ w.writerow([day[5:]] + [round(by.get(a, 0.0), 2) for a in top5])
173
+ L.append("## What ran each day? {#per-day}\n")
174
+ L.append(f'@chart type=bar data=daily_agents.csv x=day y={",".join(cols)} unit=USD '
175
+ f'title="Cost per day of the top {len(top5)} agents (API-equivalent USD, estimated)"\n')
176
+ L.append("| Day | Cost | Tokens | Agents that day (top 3) |")
177
+ L.append("| --- | --- | --- | --- |")
178
+ days_cost = {d: sum(r["cost_usd"] for r in rows) for d, rows in per_day.items()}
179
+ peak = max(days_cost, key=days_cost.get)
180
+ for day, rows in per_day.items():
181
+ cost_d, tok_d = days_cost[day], sum(r["tokens"] for r in rows)
182
+ badge = " {bad:peak}" if day == peak and len(per_day) > 2 else ""
183
+ tops = ", ".join(f"{cell(r['agent'])} {money(r['cost_usd'])}" for r in rows[:3])
184
+ L.append(f"| {dt.date.fromisoformat(day):%a %d %b} | {money(cost_d)}{badge} | {mtok(tok_d)} | "
185
+ f"{tops} (+{max(0, len(rows) - 3)} more) |")
186
+ L.append("")
163
187
 
164
188
  L.append("## How do the agents feed each other? {#map}\n")
165
189
  L.append("The full map is `agent-map.html` in this folder.\n")
@@ -268,7 +292,8 @@ def write_logs_page(snap: dict, folder: Path) -> None:
268
292
  if not j.get("log"):
269
293
  body.append("<p class=meta>this job writes no log file hivey can find.</p>")
270
294
  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>"
295
+ f"<span class=name><b>{e(j['name'])}</b><small class=desc>{e(j.get('description') or '')}</small></span>"
296
+ f"<span class=sub>{e(words)}</span><span class=when>{e(last)}</span>"
272
297
  f"<span class=issue>{e(issue[:110])}</span></summary>{details(body)}</details>")
273
298
  arows = []
274
299
  dormant = [n for n in names if n not in live and n not in usage and not logs.get(n)]
@@ -285,7 +310,9 @@ def write_logs_page(snap: dict, folder: Path) -> None:
285
310
  f" · last active {e(u.get('last_active') or '?')} · {e(cost)}"
286
311
  + (f" · {e(', '.join(u.get('models', [])[:2]))}" if u else "") + "</p>"]
287
312
  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>"
313
+ adesc = next((n.get("description", "") for n in snap["nodes"] if n["type"] == "agent" and n["label"] == name), "")
314
+ arows.append(f"<details class=row><summary><span class=emo>{emo}</span>"
315
+ f"<span class=name><b>{e(name)}</b><small class=desc>{e(adesc)}</small></span>"
289
316
  f"<span class=sub>{e(words)}</span><span class=when>{e((u.get('last_active') or '')[:16].replace('T', ' '))}</span>"
290
317
  f"<span class=issue>{e(cost)}</span></summary>{details(body)}</details>")
291
318
  if dormant:
@@ -306,9 +333,10 @@ nav a{{color:var(--accent);margin-right:18px;text-decoration:none;font-weight:60
306
333
  h1{{font-size:26px;margin:18px 0 4px}} h2{{font-size:19px;margin:34px 0 10px}}
307
334
  .lead{{color:var(--mute);margin:0 0 6px}} .counts{{font-size:17px;margin:10px 0 0}}
308
335
  .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}}
336
+ summary{{display:grid;grid-template-columns:30px minmax(220px,2fr) minmax(120px,.8fr) 130px minmax(0,1.6fr);gap:12px;align-items:center;padding:10px 14px;cursor:pointer;list-style:none}}
310
337
  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}}
338
+ .emo{{font-size:18px}} .name{{min-width:0}} .name b{{display:block}}
339
+ .desc{{display:block;color:var(--mute);font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}} .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
340
  details[open] summary{{border-bottom:1px solid var(--line)}} details>*:not(summary){{margin:10px 16px}}
313
341
  .meta{{color:var(--mute);font-size:13px}} code{{font:12.5px ui-monospace,Menlo,monospace;word-break:break-all}}
314
342
  .errs{{margin-top:0}} .errs li{{color:#d1242f}} @media (prefers-color-scheme:dark){{.errs li{{color:#ff7b72}}}}
@@ -317,7 +345,7 @@ pre{{background:var(--pre);border:1px solid var(--line);border-radius:8px;paddin
317
345
  @media (max-width:760px){{summary{{grid-template-columns:28px 1fr}} .sub,.when,.issue{{grid-column:2}}}}
318
346
  </style>
319
347
  <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>
348
+ <nav class=hv-top><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
349
  <h1>Did every job and agent run?</h1>
322
350
  <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
351
  <p class=counts>Scheduled jobs: {summary}</p>
@@ -368,7 +396,14 @@ already built: do not touch stats.archify.md or agent-stats.html.
368
396
  2. Map: {map_task}
369
397
  Costs and status go in each node's sublabel (from usage.agents and jobs in snapshot.json); keep at most
370
398
  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
399
+ 3. Descriptions: every node in snapshot.json has a "description" (what it does). For each job and agent
400
+ whose description is empty or does not say what it does (an instruction to the agent, "You are X"),
401
+ read its brief or script (first lines only) and write ONE plain sentence of at most 18 words into
402
+ ~/.hivey/agent-map/descriptions.json ({{"<node id>": "<sentence>"}}; keep the entries already there).
403
+ Then write map-meta.json in this folder: {{"nodes": {{"<map node id>": {{"refs": [<snapshot node ids
404
+ this box stands for>], "description": "<one sentence>"}}}}, "stages": {{"<stage label>": "<what this
405
+ column holds, one sentence>"}}}}. A box that folds several jobs lists all of them in refs.
406
+ 4. Run: node {archify} finalize dataflow map.json agent-map.html --quality showcase --json --out-dir review-map-llm-1
372
407
  If it fails, repair map.json and rerun with review-map-llm-2, -3 ... (at most 4 runs).
373
408
  Stop there and reply with one line: what changed."""
374
409
 
@@ -424,7 +459,8 @@ def run_llm(folder: Path, model: str, has_map: bool) -> bool:
424
459
  prompt = MAP_PROMPT.format(folder=folder, scripts=SCRIPTS, archify=archify, map_task=task)
425
460
  tools = ("Read,Write,Edit,Glob,Grep,Bash(python3:*),Bash(node:*),Bash(ls:*),Bash(cat:*),"
426
461
  "Bash(head:*),Bash(tail:*),Bash(grep:*),Bash(sed -n:*),Bash(wc:*)")
427
- cmd = [claude, "-p", prompt, "--model", model, "--allowedTools", tools, "--output-format", "text"]
462
+ cmd = [claude, "-p", prompt, "--model", model, "--allowedTools", tools, "--output-format", "text",
463
+ "--add-dir", str(STATE)] # descriptions.json and links.json live there
428
464
  log(folder, f"updating the map with {model}")
429
465
  env = {**os.environ, "HIVEY_AGENT": "hivey-agent-map"}
430
466
  token = claude_token(folder)
@@ -477,6 +513,11 @@ def nightly(scan, days: int, model: str, use_llm: bool) -> int:
477
513
  else:
478
514
  log(folder, "map: ok" if (folder / "agent-map.html").is_file() else "map: none yet")
479
515
 
516
+ try:
517
+ import enhance
518
+ enhance.enhance_folder(folder, json.loads((folder / "snapshot.json").read_text()), job_state)
519
+ except Exception as e: # the pages still work without hivey's layer
520
+ log(folder, f"enhance failed: {e}")
480
521
  if ok:
481
522
  tmp = REPORTS / ".latest-new"
482
523
  if tmp.is_symlink() or tmp.exists():