@event4u/agent-config 2.20.1 → 2.23.0

package/scripts/bench_run.py

@@ -21,6 +21,7 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(REPO_ROOT / "scripts"))
+sys.path.insert(0, str(REPO_ROOT))
 
 from _lib import script_output  # type: ignore[import-not-found]  # noqa: E402
 from _lib.bench_cost import aggregate_sessions  # noqa: E402
@@ -33,6 +34,9 @@ from _lib.bench_report import (  # noqa: E402
     write_json,
     write_markdown,
 )
+from _lib import bench_caveman  # noqa: E402
+from _lib.bench_caveman_report import build_caveman_report, render_caveman_markdown  # noqa: E402
+from _lib.bench_cost import load_pricing  # noqa: E402
 from bench_runner import run_corpus  # noqa: E402
 
 try:
@@ -41,11 +45,12 @@ except ImportError:
     script_output.error("error: PyYAML required (pip install pyyaml)")
     sys.exit(2)
 
-BENCH_RUN_VERSION = "0.1.0"
+BENCH_RUN_VERSION = "0.2.0"
 PRICING_PATH = REPO_ROOT / "bench" / "pricing.yaml"
 SESSIONS_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
 REPORTS_DIR = REPO_ROOT / "bench" / "reports"
 CORPUS_DIR = REPO_ROOT / "tests" / "eval"
+CAVEMAN_CORPUS = REPO_ROOT / "bench" / "corpora" / "caveman" / "prompts.yaml"
 BASELINE_COLLECTOR = REPO_ROOT / "scripts" / "bench_runner.py"
 
 
@@ -110,8 +115,21 @@ def main(argv: list[str] | None = None) -> int:
                     help="Override timestamp (test hook); defaults to UTC now")
     ap.add_argument("--no-write", action="store_true",
                     help="Compute the report but do not write files (dry run)")
+    ap.add_argument("--caveman", action="store_true",
+                    help="Run the caveman three-arm compression bench instead of the "
+                         "selection-accuracy bench (step-16 Phase 1).")
+    ap.add_argument("--caveman-max-prompts", type=int, default=None,
+                    help="Cap prompts in the caveman bench (smoke test).")
+    ap.add_argument("--caveman-dry-run", action="store_true",
+                    help="Caveman: skip live API calls; emit a stub report with "
+                         "zero tokens (wiring check only).")
+    ap.add_argument("--caveman-report-tag", default="caveman-v1",
+                    help="Filename tag for the caveman report (default: caveman-v1).")
     args = ap.parse_args(argv)
 
+    if args.caveman:
+        return _run_caveman(args)
+
     corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"
     if not corpus_path.is_file():
         script_output.error(f"error: corpus not found: {corpus_path}")
@@ -151,5 +169,105 @@ def main(argv: list[str] | None = None) -> int:
     return 0 if verdict["overall"] in ("pass", "partial") else 1
 
 
+class _DryRunClient:
+    """Stub client for --caveman-dry-run. Returns empty CouncilResponse-shaped objects."""
+
+    def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = 1024):
+        from ai_council.clients import CouncilResponse
+        return CouncilResponse(
+            provider="dry-run", model="stub", text="",
+            input_tokens=0, output_tokens=0, latency_ms=0, error=None,
+        )
+
+
+def _build_anthropic_client():
+    from ai_council.clients import AnthropicClient, load_anthropic_key
+    return AnthropicClient(api_key=load_anthropic_key())
+
+
+def _run_caveman(args: argparse.Namespace) -> int:
+    if not CAVEMAN_CORPUS.is_file():
+        script_output.error(f"error: caveman corpus not found: {CAVEMAN_CORPUS}")
+        return 2
+
+    if args.caveman_dry_run:
+        client = _DryRunClient()
+        transport = "dry-run"
+        model = "stub"
+    else:
+        try:
+            client = _build_anthropic_client()
+        except Exception as exc:  # noqa: BLE001
+            script_output.error(f"error: cannot build Anthropic client: {exc}")
+            return 2
+        transport = "api"
+        model = getattr(client, "model", "claude-sonnet-4-5")
+
+    def _progress(done: int, total: int, pid: str, arm: str, ar) -> None:
+        if args.quiet:
+            return
+        err = f" ERR={ar.error}" if ar.error else ""
+        print(f"[{done:>3}/{total}] {pid} · {arm:<14} "
+              f"in={ar.input_tokens:>4} out={ar.output_tokens:>4} "
+              f"{ar.latency_ms:>5}ms{err}", file=sys.stderr)
+
+    results = bench_caveman.run_caveman_bench(
+        client, CAVEMAN_CORPUS,
+        max_prompts=args.caveman_max_prompts,
+        on_progress=_progress,
+    )
+
+    rates, sourced_on = load_pricing(PRICING_PATH)
+    sonnet_rates = rates.get("sonnet", {"input": 0.0, "output": 0.0})
+
+    report = build_caveman_report(
+        results=results,
+        corpus_path_rel=str(CAVEMAN_CORPUS.relative_to(REPO_ROOT)),
+        generated_at=utc_now_iso(),
+        bench_run_version=BENCH_RUN_VERSION,
+        model=model,
+        transport=transport,
+        pricing_rates=sonnet_rates,
+        pricing_sourced_on=sourced_on,
+    )
+
+    stamp = args.stamp or utc_now_filename_stamp()
+    json_path, md_path = report_paths(REPORTS_DIR, args.caveman_report_tag, stamp)
+    # Override: caveman roadmap pins the filename to `caveman-v1.{json,md}` (no stamp).
+    fixed_json = REPORTS_DIR / f"{args.caveman_report_tag}.json"
+    fixed_md = REPORTS_DIR / f"{args.caveman_report_tag}.md"
+
+    if not args.no_write:
+        write_json(fixed_json, report)
+        fixed_md.parent.mkdir(parents=True, exist_ok=True)
+        fixed_md.write_text(render_caveman_markdown(report), encoding="utf-8")
+        # Also drop a timestamped copy for the cadence trail.
+        write_json(json_path, report)
+        json_path.with_suffix(".md").write_text(
+            render_caveman_markdown(report), encoding="utf-8"
+        )
+
+    cost = report["cost"]
+    headline = (
+        f"caveman · prompts {report['corpus']['prompt_count']} · "
+        f"calls {cost['totals']['calls']} · errors {cost['totals']['errors']} · "
+        f"vs_raw med {report['caveman']['aggregate']['savings_vs_raw']['median']:.2%} · "
+        f"vs_terse med {report['caveman']['aggregate']['savings_vs_terse']['median']:.2%} · "
+        f"cost ${cost['totals']['total_cost_usd']:.6f}"
+    )
+    if args.quiet:
+        print(headline)
+        if not args.no_write:
+            print(f"report: {fixed_md.relative_to(REPO_ROOT)}")
+    else:
+        print(render_caveman_markdown(report))
+        if not args.no_write:
+            print(f"\n→ json:     {fixed_json.relative_to(REPO_ROOT)}")
+            print(f"→ markdown: {fixed_md.relative_to(REPO_ROOT)}")
+            print(f"→ trail:    {json_path.relative_to(REPO_ROOT)}")
+
+    return 0 if cost["totals"]["errors"] == 0 else 1
+
+
 if __name__ == "__main__":
     sys.exit(main(sys.argv[1:]))

package/scripts/caveman_stats.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Caveman per-session / per-conversation / lifetime token-delta lens.
+
+Reads sessions.jsonl, groups by sessionId + conversation_id, emits per-row
+caveman delta tokens. Honors the suspended-multiplier contract in
+`docs/contracts/caveman-telemetry.md` (delta = 0 while suspended).
+"""
+from __future__ import annotations
+import argparse, json, sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+TELEMETRY_DOC = REPO_ROOT / "docs" / "contracts" / "caveman-telemetry.md"
+
+# Mirrors `docs/contracts/caveman-telemetry.md` `v1` constants.
+MULTIPLIER_VERSION = "v1"
+MULTIPLIER_VALUE = 0.9155
+MULTIPLIER_ACTIVE = False  # suspended pending v2
+
+
+def _load(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    rows: list[dict] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def _delta(row: dict) -> int:
+    """Per-row delta with suspended-multiplier guard."""
+    if not MULTIPLIER_ACTIVE:
+        return 0
+    explicit = row.get("caveman_delta_tokens")
+    if isinstance(explicit, (int, float)):
+        return int(explicit)
+    compressed = row.get("caveman_compressed_tokens")
+    if isinstance(compressed, (int, float)) and compressed > 0:
+        return int(compressed * MULTIPLIER_VALUE - compressed)
+    return 0
+
+
+def aggregate(rows: list[dict]) -> dict:
+    _zero = lambda: {"sessions": 0, "delta_tokens": 0, "compressed_tokens": 0}
+    by_session: dict[str, dict] = defaultdict(_zero)
+    by_conv: dict[str, dict] = defaultdict(_zero)
+    lifetime = _zero()
+    for row in rows:
+        sid = str(row.get("sessionId") or row.get("session_id") or "unknown")
+        cid = str(row.get("conversation_id") or "unknown")
+        delta = _delta(row)
+        comp = int(row.get("caveman_compressed_tokens") or 0)
+        for bucket in (by_session[sid], by_conv[cid], lifetime):
+            bucket["sessions"] += 1
+            bucket["delta_tokens"] += delta
+            bucket["compressed_tokens"] += comp
+    return {
+        "schema_version": "caveman-stats/v1",
+        "multiplier_version": MULTIPLIER_VERSION,
+        "multiplier_value": MULTIPLIER_VALUE,
+        "multiplier_active": MULTIPLIER_ACTIVE,
+        "lifetime": lifetime,
+        "by_session": dict(by_session),
+        "by_conversation": dict(by_conv),
+    }
+
+
+def render_text(report: dict) -> str:
+    lines = [
+        f"caveman-stats {report['schema_version']} · multiplier {report['multiplier_version']}"
+        f" ({'ACTIVE' if report['multiplier_active'] else 'SUSPENDED'}) · "
+        f"value {report['multiplier_value']:.4f}",
+        "",
+        f"  lifetime: {report['lifetime']['sessions']} sessions · "
+        f"delta_tokens = {report['lifetime']['delta_tokens']:+,} · "
+        f"compressed_tokens = {report['lifetime']['compressed_tokens']:,}",
+        "",
+        "  by conversation:",
+    ]
+    for cid, b in sorted(report["by_conversation"].items()):
+        lines.append(
+            f"    {cid}: {b['sessions']} sessions · "
+            f"delta = {b['delta_tokens']:+,} · compressed = {b['compressed_tokens']:,}"
+        )
+    if not report["multiplier_active"]:
+        lines += [
+            "",
+            "  Note: multiplier suspended — see docs/contracts/caveman-telemetry.md",
+            "  (delta_tokens = 0 until kill-criterion satisfied in caveman-v2).",
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--input", type=Path, default=DEFAULT_JSONL)
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args(argv)
+
+    rows = _load(args.input)
+    report = aggregate(rows)
+
+    if args.format == "json":
+        print(json.dumps(report, indent=2))
+    else:
+        print(render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_command_count_messaging.py

@@ -17,7 +17,7 @@ Canonical counts:
 Patterns checked (per file):
 
     README.md
-      hero row     "<strong>{N} Commands</strong>"            → active
+      hero badge   "/badge/Commands-{N}-…"                    → active
       browse line  "Browse all {N} active commands"           → active
       browse meta  "{N} files total"                          → total
       browse meta  "{N} are deprecation shims"                → shims
@@ -84,7 +84,7 @@ def main() -> int:
 
     checks = [
         # README.md
-        (README, r"<strong>(\d+) Commands</strong>", active, "hero row"),
+        (README, r"/badge/Commands-(\d+)-", active, "hero badge"),
         (README, r"Browse all (\d+) active commands", active, "browse line"),
         (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
         # docs/getting-started.md

package/scripts/compress_memory.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Input-side memory compression — Phase 2 of step-16-caveman-substance.
+
+Rewrites memory files (AGENTS.md, CLAUDE.md, .cursorrules, ...) to caveman
+grammar (drop articles / auxiliaries) while preserving carve-outs byte-for-byte
+(code blocks, numbered-options, status markers, Iron-Law ALL-CAPS, backtick
+spans). Writes `.original.md` backup before mutating. Gated by Phase 0
+`validate_safe_paths.assert_safe`. Idempotency guard: `original_sha256:` +
+`compressed_at:` frontmatter refuse re-compression on body-hash drift.
+
+CLI: `compress_memory.py <path> [--check|--decompress]`. Stdlib-only.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from validate_safe_paths import SensitivePathError, assert_safe  # noqa: E402
+
+__all__ = ["compress_text", "compress_file", "decompress_file", "CompressionRefused"]
+
+
+class CompressionRefused(RuntimeError):
+    """Raised when the target is already compressed and body hash diverged."""
+
+
+# Carve-out region patterns — mirrors caveman-speak.md § Carve-outs (1–7).
+RE_FENCE = re.compile(r"^```")
+RE_NUMBERED = re.compile(r"^>?\s*\d+\.\s")
+RE_STATUS = re.compile(r"^\s*(?:❌|⚠️|✅)")
+RE_IRONLAW = re.compile(r"^[A-Z][A-Z0-9 ,.\-_/']{3,}$")
+RE_BACKTICK_SPAN = re.compile(r"`[^`\n]+`")
+RE_FRONTMATTER = re.compile(r"^---\s*$")
+WORD_RE = re.compile(r"\b[A-Za-z]+\b")
+DROP_TOKENS = {"the", "a", "an", "is", "are", "was", "were", "be", "been",
+               "being", "that", "which"}
+
+
+def _compress_words(text: str) -> str:
+    out = WORD_RE.sub(lambda m: "" if m.group(0).lower() in DROP_TOKENS else m.group(0), text)
+    out = re.sub(r"[ \t]{2,}", " ", out)
+    return re.sub(r" +([,.;:!?])", r"\1", out)
+
+
+def _compress_prose_line(line: str) -> str:
+    """Compress a prose line; preserve backtick-spans byte-for-byte."""
+    parts: list[str] = []
+    last = 0
+    for span in RE_BACKTICK_SPAN.finditer(line):
+        parts.append(_compress_words(line[last:span.start()]))
+        parts.append(span.group(0))
+        last = span.end()
+    parts.append(_compress_words(line[last:]))
+    return "".join(parts)
+
+
+def compress_text(body: str) -> str:
+    """Compress a memory-file body. Idempotent on already-caveman text."""
+    out: list[str] = []
+    in_fence = False
+    for raw in body.splitlines(keepends=True):
+        stripped = raw.rstrip("\r\n")
+        if RE_FENCE.match(stripped):
+            in_fence = not in_fence
+            out.append(raw)
+            continue
+        if in_fence or RE_NUMBERED.match(stripped) or RE_STATUS.match(stripped) \
+                or RE_IRONLAW.match(stripped.strip()):
+            out.append(raw)
+            continue
+        out.append(_compress_prose_line(raw))
+    return "".join(out)
+
+
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or not RE_FRONTMATTER.match(lines[0].rstrip()):
+        return "", text
+    for idx in range(1, len(lines)):
+        if RE_FRONTMATTER.match(lines[idx].rstrip()):
+            return "".join(lines[: idx + 1]), "".join(lines[idx + 1:])
+    return "", text
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _has_sha_marker(fm: str) -> bool:
+    return bool(re.search(r"^original_sha256:\s*[0-9a-f]{64}\s*$", fm, re.MULTILINE))
+
+
+def _inject_frontmatter(fm: str, sha: str, ts: str) -> str:
+    drop = re.compile(r"^(original_sha256|compressed_at):.*$", re.MULTILINE)
+    inner = drop.sub("", fm.strip().strip("-").strip()).strip() if fm else ""
+    body = inner + ("\n" if inner else "")
+    return f"---\n{body}original_sha256: {sha}\ncompressed_at: {ts}\n---\n"
+
+
+def _backup_path(target: Path) -> Path:
+    return target.parent / (target.name + ".original.md")
+
+
+def compress_file(target: Path) -> Path:
+    assert_safe(target)
+    text = target.read_text(encoding="utf-8")
+    fm, body = _split_frontmatter(text)
+    if _has_sha_marker(fm):
+        if _sha256(compress_text(body)) != _sha256(body):
+            raise CompressionRefused(
+                f"{target}: body hash diverged; decompress first "
+                f"(`scripts/compress_memory.py {target} --decompress`)."
+            )
+        return target
+    backup = _backup_path(target)
+    backup.write_text(text, encoding="utf-8")
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    target.write_text(
+        _inject_frontmatter(fm, _sha256(body), ts) + compress_text(body),
+        encoding="utf-8",
+    )
+    return backup
+
+
+def decompress_file(target: Path) -> Path:
+    assert_safe(target)
+    backup = _backup_path(target)
+    if not backup.is_file():
+        raise FileNotFoundError(f"no backup at {backup}")
+    target.write_text(backup.read_text(encoding="utf-8"), encoding="utf-8")
+    backup.unlink()
+    return target
+
+
+def _main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Compress memory files to caveman grammar.")
+    ap.add_argument("path", type=Path)
+    grp = ap.add_mutually_exclusive_group()
+    grp.add_argument("--check", action="store_true", help="exit 0 if safe; no writes")
+    grp.add_argument("--decompress", action="store_true", help="restore .original.md")
+    args = ap.parse_args(argv)
+    try:
+        if args.check:
+            assert_safe(args.path)
+            return 0
+        if args.decompress:
+            decompress_file(args.path)
+            print(f"decompressed: {args.path}")
+            return 0
+        backup = compress_file(args.path)
+        print(f"compressed: {args.path}  (backup: {backup})")
+        return 0
+    except SensitivePathError as exc:
+        print(f"error: refused: {exc}", file=sys.stderr)
+        return 2
+    except CompressionRefused as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main(sys.argv[1:]))

package/scripts/cost_by_conversation.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Group cost-tracking sessions by conversation_id (Ruflo `conversation.mjs` `5b71c7a` ref)."""
+from __future__ import annotations
+import argparse, json, sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+
+
+def _load(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        try:
+            out.append(json.loads(s))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def group(rows: list[dict]) -> dict:
+    by_conv: dict = defaultdict(lambda: {
+        "sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0,
+        "output_tokens": 0, "caveman_delta_tokens": 0,
+        "by_model": defaultdict(lambda: {"sessions": 0, "cost_usd": 0.0}),
+    })
+    for row in rows:
+        cid = str(row.get("conversation_id") or "unknown")
+        b = by_conv[cid]
+        cost = float(row.get("total_cost_usd") or 0)
+        b["sessions"] += 1
+        b["total_cost_usd"] += cost
+        b["input_tokens"] += int(row.get("input_tokens") or 0)
+        b["output_tokens"] += int(row.get("output_tokens") or 0)
+        b["caveman_delta_tokens"] += int(row.get("caveman_delta_tokens") or 0)
+        m = b["by_model"][str(row.get("model") or "unknown")]
+        m["sessions"] += 1
+        m["cost_usd"] += cost
+    return {cid: {**b, "by_model": dict(b["by_model"])} for cid, b in by_conv.items()}
+
+
+def render_text(report: dict) -> str:
+    if not report:
+        return "cost-by-conversation: no rows.\n"
+    lines = ["cost-by-conversation lens · grouped by conversation_id", ""]
+    for cid, b in sorted(report.items()):
+        lines.append(
+            f"  {cid}: {b['sessions']} sessions · ${b['total_cost_usd']:.4f} · "
+            f"in {b['input_tokens']:,} · out {b['output_tokens']:,} · "
+            f"caveman_delta {b['caveman_delta_tokens']:+,}"
+        )
+        for model, m in sorted(b["by_model"].items()):
+            lines.append(f"      {model}: {m['sessions']} sessions · ${m['cost_usd']:.4f}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--input", type=Path, default=DEFAULT_JSONL)
+    p.add_argument("--format", choices=["text", "json"], default="text")
+    args = p.parse_args(argv)
+    report = group(_load(args.input))
+    if args.format == "json":
+        print(json.dumps({"schema_version": "cost-by-conversation/v1",
+                          "by_conversation": report}, indent=2))
+    else:
+        print(render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cost_summary.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Emit `cost-summary/v1` JSON per `docs/contracts/cost-summary-schema.md`.
+
+Reads `agents/cost-tracking/sessions.jsonl` (or `--input`), aggregates by
+session, conversation, and model. Honors the caveman suspended-multiplier
+contract (delta = 0 while suspended; see `caveman-telemetry.md`).
+"""
+from __future__ import annotations
+import argparse, json, sys
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+SCHEMA = "cost-summary/v1"
+MULTIPLIER_VERSION = "v1"
+MULTIPLIER_ACTIVE = False
+
+
+def _load(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        try:
+            out.append(json.loads(s))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _delta(row: dict) -> int:
+    if not MULTIPLIER_ACTIVE:
+        return 0
+    return int(row.get("caveman_delta_tokens") or 0)
+
+
+def _zero_kv() -> dict:
+    return {"sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0,
+            "output_tokens": 0, "caveman_delta_tokens": 0}
+
+
+def _zero_model() -> dict:
+    return {"sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0, "output_tokens": 0}
+
+
+def aggregate(rows: list[dict]) -> dict:
+    by_sess: dict = defaultdict(_zero_kv)
+    by_conv: dict = defaultdict(_zero_kv)
+    by_model: dict = defaultdict(_zero_model)
+    totals = _zero_kv()
+    for row in rows:
+        sid = str(row.get("sessionId") or row.get("session_id") or "unknown")
+        cid = str(row.get("conversation_id") or "unknown")
+        model = str(row.get("model") or "unknown")
+        cost = float(row.get("total_cost_usd") or 0)
+        itok = int(row.get("input_tokens") or 0)
+        otok = int(row.get("output_tokens") or 0)
+        delta = _delta(row)
+        for bucket in (by_sess[sid], by_conv[cid], totals):
+            bucket["sessions"] += 1
+            bucket["total_cost_usd"] += cost
+            bucket["input_tokens"] += itok
+            bucket["output_tokens"] += otok
+            bucket["caveman_delta_tokens"] += delta
+        m = by_model[model]
+        m["sessions"] += 1
+        m["total_cost_usd"] += cost
+        m["input_tokens"] += itok
+        m["output_tokens"] += otok
+    totals["caveman_multiplier_version"] = MULTIPLIER_VERSION
+    totals["caveman_multiplier_active"] = MULTIPLIER_ACTIVE
+    return {
+        "schema_version": SCHEMA,
+        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "totals": totals,
+        "by_session": [{"key": k, **v} for k, v in sorted(by_sess.items())],
+        "by_conversation": [{"key": k, **v} for k, v in sorted(by_conv.items())],
+        "by_model": [{"model": k, **v} for k, v in sorted(by_model.items())],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--input", type=Path, default=DEFAULT_JSONL)
+    p.add_argument("--format", choices=["json"], default="json")
+    args = p.parse_args(argv)
+    print(json.dumps(aggregate(_load(args.input)), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/update_counts.py

@@ -55,11 +55,13 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
         [
             (r"(Browse all )(\d+)( commands\])", "commands"),
             (r"(package \(rules \+ )(\d+)( skills)", "skills"),
-            # Hero line: **NNN Skills** · **NNN Rules** · **NNN Commands** · **NNN Guidelines**
-            (r"(<strong>)(\d+)( Skills</strong>)", "skills"),
-            (r"(<strong>)(\d+)( Rules</strong>)", "rules"),
-            (r"(<strong>)(\d+)( Guidelines</strong>)", "guidelines"),
-            # NOTE: hero `<strong>N Commands</strong>` and tools-blurb
+            # Hero badges: shields.io URLs `Skills-NNN-<color>` etc.
+            # Format: https://img.shields.io/badge/<Label>-<N>-<hex>?style=flat-square
+            (r"(/badge/Skills-)(\d+)(-)", "skills"),
+            (r"(/badge/Rules-)(\d+)(-)", "rules"),
+            (r"(/badge/Guidelines-)(\d+)(-)", "guidelines"),
+            (r"(/badge/Personas-)(\d+)(-)", "personas"),
+            # NOTE: hero `Commands-N` badge and tools-blurb
             # `skills + N native commands` are owned by
             # `check_command_count_messaging.py` (Phase-1.2 of
             # road-to-pr-34-followups). Those surfaces advertise the