agent-usage-tracker 0.1.0__py3-none-any.whl

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.
Files changed (113) hide show
  1. agent_usage_tracker/__init__.py +8 -0
  2. agent_usage_tracker/backup.py +225 -0
  3. agent_usage_tracker/cli.py +479 -0
  4. agent_usage_tracker/collectors/__init__.py +115 -0
  5. agent_usage_tracker/collectors/_util.py +310 -0
  6. agent_usage_tracker/collectors/activity_common.py +294 -0
  7. agent_usage_tracker/collectors/activitywatch.py +394 -0
  8. agent_usage_tracker/collectors/claude_code.py +484 -0
  9. agent_usage_tracker/collectors/claude_code_activity.py +317 -0
  10. agent_usage_tracker/collectors/codex.py +612 -0
  11. agent_usage_tracker/collectors/commits.py +154 -0
  12. agent_usage_tracker/collectors/cursor.py +193 -0
  13. agent_usage_tracker/collectors/cursor_api.py +247 -0
  14. agent_usage_tracker/collectors/cursor_cli.py +592 -0
  15. agent_usage_tracker/collectors/cursor_sdk.py +95 -0
  16. agent_usage_tracker/collectors/generic_sdk.py +100 -0
  17. agent_usage_tracker/collectors/pi.py +397 -0
  18. agent_usage_tracker/collectors/session_digest.py +379 -0
  19. agent_usage_tracker/collectors/t3.py +490 -0
  20. agent_usage_tracker/config.py +392 -0
  21. agent_usage_tracker/coverage.py +615 -0
  22. agent_usage_tracker/coverage_catalog.json +588 -0
  23. agent_usage_tracker/cursor_run.py +62 -0
  24. agent_usage_tracker/diagnostics.py +74 -0
  25. agent_usage_tracker/episode_store.py +78 -0
  26. agent_usage_tracker/event.py +132 -0
  27. agent_usage_tracker/git_day_cache.py +128 -0
  28. agent_usage_tracker/git_days.py +499 -0
  29. agent_usage_tracker/git_safe.py +58 -0
  30. agent_usage_tracker/harness_inventory.py +208 -0
  31. agent_usage_tracker/history_steers.py +88 -0
  32. agent_usage_tracker/improve/__init__.py +1 -0
  33. agent_usage_tracker/improve/case_view.py +112 -0
  34. agent_usage_tracker/improve/cli.py +138 -0
  35. agent_usage_tracker/improve/desktop.py +347 -0
  36. agent_usage_tracker/improve/evidence.py +322 -0
  37. agent_usage_tracker/improve/judge.py +671 -0
  38. agent_usage_tracker/improve/proposals.py +72 -0
  39. agent_usage_tracker/improve/rubric.py +360 -0
  40. agent_usage_tracker/improve/rubrics/avoidable_recovery.md +20 -0
  41. agent_usage_tracker/improve/rubrics/code_quality.md +22 -0
  42. agent_usage_tracker/improve/rubrics/completion_supported.md +20 -0
  43. agent_usage_tracker/improve/rubrics/redundant_tests.md +21 -0
  44. agent_usage_tracker/improve/rubrics/verbosity.md +21 -0
  45. agent_usage_tracker/improve/runtime.py +117 -0
  46. agent_usage_tracker/improve/schedule.py +291 -0
  47. agent_usage_tracker/improve/search_check.py +563 -0
  48. agent_usage_tracker/improve/store.py +244 -0
  49. agent_usage_tracker/improve/studies.py +285 -0
  50. agent_usage_tracker/improve/study_cli.py +46 -0
  51. agent_usage_tracker/improve/study_decision.py +121 -0
  52. agent_usage_tracker/improve/study_followup.py +174 -0
  53. agent_usage_tracker/improve/t3.py +269 -0
  54. agent_usage_tracker/improve/trial.py +318 -0
  55. agent_usage_tracker/improve/validation.py +148 -0
  56. agent_usage_tracker/inspector.py +350 -0
  57. agent_usage_tracker/label/__init__.py +22 -0
  58. agent_usage_tracker/label/backends.py +742 -0
  59. agent_usage_tracker/label/bakeoff.py +661 -0
  60. agent_usage_tracker/label/baseline.py +173 -0
  61. agent_usage_tracker/label/clef.py +258 -0
  62. agent_usage_tracker/label/context.py +382 -0
  63. agent_usage_tracker/label/core.py +355 -0
  64. agent_usage_tracker/label/covered_run.py +92 -0
  65. agent_usage_tracker/label/evalset.py +154 -0
  66. agent_usage_tracker/label/gold.py +209 -0
  67. agent_usage_tracker/label/local.py +326 -0
  68. agent_usage_tracker/label/local_parallel.py +232 -0
  69. agent_usage_tracker/label/merge.py +57 -0
  70. agent_usage_tracker/label/outcome_coverage.py +57 -0
  71. agent_usage_tracker/label/replay.py +194 -0
  72. agent_usage_tracker/label/run.py +339 -0
  73. agent_usage_tracker/label/tasks.py +579 -0
  74. agent_usage_tracker/label/teach.py +145 -0
  75. agent_usage_tracker/local_page.py +128 -0
  76. agent_usage_tracker/manual_time.py +69 -0
  77. agent_usage_tracker/net.py +23 -0
  78. agent_usage_tracker/observation_cli.py +65 -0
  79. agent_usage_tracker/observation_report.py +116 -0
  80. agent_usage_tracker/observation_server.py +110 -0
  81. agent_usage_tracker/observations.py +365 -0
  82. agent_usage_tracker/outcome_git.py +383 -0
  83. agent_usage_tracker/outcomes.py +464 -0
  84. agent_usage_tracker/pricing.py +248 -0
  85. agent_usage_tracker/push.py +530 -0
  86. agent_usage_tracker/redact.py +45 -0
  87. agent_usage_tracker/repo_keys.py +165 -0
  88. agent_usage_tracker/review.py +252 -0
  89. agent_usage_tracker/scan.py +472 -0
  90. agent_usage_tracker/scheduled.py +164 -0
  91. agent_usage_tracker/sdk.py +79 -0
  92. agent_usage_tracker/sink.py +82 -0
  93. agent_usage_tracker/sink_stack/README.md +71 -0
  94. agent_usage_tracker/sink_stack/apply.sh +63 -0
  95. agent_usage_tracker/sink_stack/compose.yaml +94 -0
  96. agent_usage_tracker/sink_stack/env.example +20 -0
  97. agent_usage_tracker/sink_stack/grafana/dashboards/agents-effort.json +634 -0
  98. agent_usage_tracker/sink_stack/grafana/dashboards/agents-usage.json +1279 -0
  99. agent_usage_tracker/sink_stack/grafana/provisioning/dashboards/aut.yaml +9 -0
  100. agent_usage_tracker/sink_stack/grafana/provisioning/datasources/agents.yaml +16 -0
  101. agent_usage_tracker/sink_stack/sql/01_schema.sql +1186 -0
  102. agent_usage_tracker/sink_stack/sql/02_price.sql +60 -0
  103. agent_usage_tracker/sink_stack/sql/03_effort.sql +1180 -0
  104. agent_usage_tracker/sink_stack/sql/04_grants.sql +149 -0
  105. agent_usage_tracker/sink_stack/sql/refresh.sql +66 -0
  106. agent_usage_tracker/sources.py +180 -0
  107. agent_usage_tracker/state.py +191 -0
  108. agent_usage_tracker/telemetry.py +165 -0
  109. agent_usage_tracker-0.1.0.dist-info/METADATA +366 -0
  110. agent_usage_tracker-0.1.0.dist-info/RECORD +113 -0
  111. agent_usage_tracker-0.1.0.dist-info/WHEEL +4 -0
  112. agent_usage_tracker-0.1.0.dist-info/entry_points.txt +3 -0
  113. agent_usage_tracker-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,615 @@
1
+ """Show which local evidence is available and where work can remain unobserved."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from contextlib import closing
6
+ from datetime import date, datetime, timedelta, timezone
7
+ import hashlib
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ import re
12
+ import sqlite3
13
+ import stat
14
+ from typing import Any, Final
15
+ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
16
+
17
+ from .config import Config
18
+ from .state import _locked, atomic_write_text, state_path
19
+
20
+ MAX_JSON_BYTES = 8 * 1024 * 1024
21
+ MAX_STATE_JSON_BYTES = 64 * 1024 * 1024
22
+ MAX_ENTRIES = 4096
23
+ MAX_DEPTH = 8
24
+ MAX_COLLECTORS = 128
25
+ FRESH_HOURS = 12
26
+ _CAPABILITIES = ("requests", "commands", "results", "usage", "outcomes")
27
+ _NATIVE = {"claude_code", "codex", "pi"}
28
+ _ACTIVITY = {"steer", "interrupt", "rejection", "commit", "pr", "turn", "compaction",
29
+ "invoke", "link", "label", "eval", "steer_estimate"}
30
+ _ID = re.compile(r"[a-z][a-z0-9_]{0,63}\Z")
31
+ _ERROR_CLASSES = {"ValueError", "TypeError", "OSError", "PermissionError", "FileNotFoundError",
32
+ "IsADirectoryError", "NotADirectoryError", "TimeoutError", "ConnectionError",
33
+ "ConnectionRefusedError", "BrokenPipeError", "RuntimeError", "KeyError",
34
+ "AttributeError", "OverflowError", "RecursionError", "UnicodeDecodeError",
35
+ "JSONDecodeError", "CollectorUnavailable", "AutError", "DeliveryError",
36
+ "OperationalError", "DatabaseError", "IntegrityError", "HTTPError", "URLError",
37
+ "KeyboardInterrupt", "SystemExit", "CancelledError"}
38
+
39
+
40
+ def observations_path() -> Path:
41
+ return state_path().parent / "scan-observations.json"
42
+
43
+
44
+ def report_path() -> Path:
45
+ return state_path().parent / "coverage.json"
46
+
47
+
48
+ def _read_json(path: Path, limit: int = MAX_JSON_BYTES) -> tuple[str, dict[str, Any]]:
49
+ try:
50
+ # A configured pipe/device must not block a read-only diagnosis.
51
+ fd = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
52
+ with os.fdopen(fd, "rb") as handle:
53
+ meta = os.fstat(handle.fileno())
54
+ if not stat.S_ISREG(meta.st_mode):
55
+ return "invalid", {}
56
+ if meta.st_size > limit:
57
+ return "limited", {}
58
+ raw = handle.read(limit + 1)
59
+ if len(raw) > limit:
60
+ return "limited", {}
61
+ value = json.loads(raw)
62
+ return ("available", value) if isinstance(value, dict) else ("invalid", {})
63
+ except FileNotFoundError:
64
+ return "missing", {}
65
+ except (OSError, ValueError, RecursionError):
66
+ return "unreadable", {}
67
+
68
+
69
+ def _count(value: object) -> int:
70
+ return value if type(value) is int and 0 <= value <= 2**63 - 1 else 0
71
+
72
+
73
+ def _stamp(value: object) -> datetime | None:
74
+ try:
75
+ stamp = datetime.fromisoformat(value.replace("Z", "+00:00")) if isinstance(value, str) else None
76
+ return stamp if stamp and stamp.tzinfo is not None else None
77
+ except ValueError:
78
+ return None
79
+
80
+
81
+ def _clean_row(row: dict[str, Any]) -> dict[str, Any] | None:
82
+ name = row.get("collector")
83
+ if not isinstance(name, str) or not _ID.fullmatch(name):
84
+ return None
85
+ from .diagnostics import Diagnostics, capture, observe_client
86
+
87
+ diagnostics = row.get("diagnostics")
88
+ diagnostics = diagnostics if isinstance(diagnostics, dict) else {}
89
+ clients = diagnostics.get("clients")
90
+ observed = Diagnostics()
91
+ with capture(observed):
92
+ for client in clients[:32] if isinstance(clients, list) else []:
93
+ if isinstance(client, str) and re.fullmatch(r"unknown:[a-f0-9]{16}", client):
94
+ observed.clients.add(client)
95
+ else:
96
+ observe_client(client)
97
+ skipped = diagnostics.get("skipped")
98
+ skipped = skipped if isinstance(skipped, dict) else {}
99
+ activity = row.get("activity")
100
+ activity = activity if isinstance(activity, dict) else {}
101
+ valid = (all(type(row.get(k)) is int and 0 <= row[k] <= 2**63 - 1
102
+ for k in ("usage_events", "human_classifications"))
103
+ and isinstance(row.get("activity"), dict)
104
+ and all(type(v) is int and 0 <= v <= 2**63 - 1 for v in activity.values())
105
+ and _stamp(row.get("started_at")) is not None
106
+ and _stamp(row.get("finished_at")) is not None)
107
+ return {"collector": name,
108
+ "status": row.get("status") if valid and row.get("status") in {
109
+ "ok", "degraded", "error", "unavailable"}
110
+ else "unknown",
111
+ "error": row.get("error") if isinstance(row.get("error"), str)
112
+ and row["error"] in _ERROR_CLASSES else "collector_error" if row.get("error") else None,
113
+ "started_at": (_stamp(row.get("started_at")) or datetime.min.replace(
114
+ tzinfo=timezone.utc)).isoformat(),
115
+ "finished_at": (_stamp(row.get("finished_at")) or datetime.min.replace(
116
+ tzinfo=timezone.utc)).isoformat(),
117
+ "usage_events": _count(row.get("usage_events")),
118
+ "human_classifications": _count(row.get("human_classifications")),
119
+ "activity": {kind: _count(activity.get(kind)) for kind in sorted(_ACTIVITY)
120
+ if _count(activity.get(kind))},
121
+ "diagnostics": {"skipped": {key: _count(skipped.get(key)) for key in
122
+ ("malformed_records", "activity_errors", "unreadable_files", "missing_payloads")
123
+ if _count(skipped.get(key))}, "clients": sorted(observed.clients),
124
+ "client_overflow": bool(diagnostics.get("client_overflow")) or
125
+ isinstance(clients, list) and len(clients) > 32}}
126
+
127
+
128
+ def save_scan_observations(rows: list[dict[str, Any]]) -> None:
129
+ """Merge collector receipts without replacing another collector's most recent run."""
130
+ path = observations_path()
131
+ with _locked(path):
132
+ _, data = _read_json(path)
133
+ previous = data.get("collectors", {})
134
+ merged = {}
135
+ if isinstance(previous, dict):
136
+ for value in list(previous.values())[:MAX_COLLECTORS]:
137
+ clean = _clean_row(value) if isinstance(value, dict) else None
138
+ if clean:
139
+ merged[clean["collector"]] = clean
140
+ for row in rows[:MAX_COLLECTORS]:
141
+ clean = _clean_row(row)
142
+ if clean:
143
+ previous_row = merged.get(clean["collector"], {})
144
+ previous_at = _stamp(previous_row.get("finished_at"))
145
+ incoming_at = _stamp(clean.get("finished_at"))
146
+ if (previous_at and previous_at <= datetime.now(timezone.utc)
147
+ and (incoming_at is None or previous_at > incoming_at)):
148
+ continue
149
+ merged[clean["collector"]] = clean
150
+ if len(merged) > MAX_COLLECTORS:
151
+ raise ValueError("scan receipt collector limit exceeded")
152
+ atomic_write_text(path, json.dumps({"version": 1, "collectors": merged}, sort_keys=True))
153
+
154
+
155
+ def _issue(issues: list[dict[str, str]], code: str, source: str, severity: str = "warning") -> None:
156
+ item = {"code": code, "source_id": source, "severity": severity}
157
+ if item not in issues:
158
+ issues.append(item)
159
+
160
+
161
+ def _receipt(raw: object, now: datetime) -> dict[str, Any]:
162
+ row = _clean_row(raw) if isinstance(raw, dict) else None
163
+ if row is None:
164
+ return {"receipt_status": "missing", "activity_state": "unknown"}
165
+ counts_valid = (isinstance(raw, dict) and all(
166
+ type(raw.get(k)) is int and 0 <= raw[k] <= 2**63 - 1
167
+ for k in ("usage_events", "human_classifications"))
168
+ and isinstance(raw.get("activity"), dict)
169
+ and all(type(v) is int and 0 <= v <= 2**63 - 1 for v in raw["activity"].values()))
170
+ stamp = _stamp(row["finished_at"])
171
+ start = _stamp(raw.get("started_at")) if isinstance(raw, dict) else None
172
+ status = ("unknown" if not counts_valid or stamp is None or stamp > now
173
+ or start is None or start > stamp or row["status"] == "unknown" else
174
+ "stale" if now - stamp > timedelta(hours=FRESH_HOURS) else "fresh")
175
+ active = row["usage_events"] + row["human_classifications"] + sum(row["activity"].values())
176
+ lost = any(row["diagnostics"]["skipped"].values())
177
+ return {**row, "receipt_status": status,
178
+ "activity_state": ("observed" if active else "unknown" if lost else "idle")
179
+ if status == "fresh" and row["status"] == "ok" else "unknown",
180
+ "count_scope": "locally_normalized_emitted_not_acknowledged"}
181
+
182
+
183
+ def _roots(cfg: Config, engine: str) -> list[Path]:
184
+ from .sources import engine_homes
185
+
186
+ if engine in _NATIVE:
187
+ suffix = "projects" if engine == "claude_code" else "sessions"
188
+ return [home / suffix for home in engine_homes(cfg.home, engine)]
189
+ if engine == "cursor":
190
+ from .collectors.cursor import cursor_db
191
+ return [cursor_db(cfg)]
192
+ if engine == "cursor_cli":
193
+ return [cfg.home / ".cursor/chats", cfg.home / ".cursor/projects"]
194
+ if engine == "t3":
195
+ from .collectors.t3 import database_path
196
+ return [database_path(cfg.home)]
197
+ # Globs, network services and credentials are never probed by doctor.
198
+ return []
199
+
200
+
201
+ def _metadata(root: Path, files: dict[str, Any], budget: list[int], engine: str,
202
+ limit: int | None = None) -> dict[str, Any]:
203
+ stop_at = min(MAX_ENTRIES, budget[0] + limit) if limit is not None else MAX_ENTRIES
204
+ info: dict[str, Any] = {"path": str(root), "status": "available", "files": 0,
205
+ "bytes": 0, "unread_bytes": 0, "limited": False}
206
+
207
+ def visit(path: Path, depth: int) -> None:
208
+ if budget[0] >= stop_at:
209
+ info["limited"] = True
210
+ if path == root:
211
+ info["status"] = "unknown"
212
+ return
213
+ budget[0] += 1
214
+ try:
215
+ meta = path.lstat()
216
+ if stat.S_ISLNK(meta.st_mode):
217
+ # The root can be an explicitly registered alias; never follow child links.
218
+ if path != root:
219
+ info["limited"] = True
220
+ return
221
+ meta = path.stat()
222
+ if path == root and (
223
+ engine in _NATIVE and not stat.S_ISDIR(meta.st_mode)
224
+ or engine in {"cursor", "t3"} and not stat.S_ISREG(meta.st_mode)):
225
+ info["status"] = "unreadable"
226
+ return
227
+ if stat.S_ISREG(meta.st_mode):
228
+ recognized = (path == root or
229
+ engine == "claude_code" and path.suffix == ".jsonl" or
230
+ engine == "codex" and path.name.startswith("rollout-") and path.suffix == ".jsonl" or
231
+ engine == "pi" and path.suffix == ".jsonl" or
232
+ engine == "cursor_cli" and path.name in {"store.db", "index.db"})
233
+ if not recognized:
234
+ return
235
+ info["files"] += 1
236
+ info["bytes"] += meta.st_size
237
+ previous = files.get(str(path))
238
+ off = _count(previous.get("off")) if isinstance(previous, dict) else 0
239
+ same = isinstance(previous, dict) and previous.get("ino") == meta.st_ino
240
+ # SQLite watermarks are logical IDs, not byte offsets.
241
+ if path.suffix == ".jsonl":
242
+ info["unread_bytes"] += (meta.st_size - off
243
+ if same and off <= meta.st_size else meta.st_size)
244
+ elif stat.S_ISDIR(meta.st_mode):
245
+ if depth >= MAX_DEPTH:
246
+ info["limited"] = True
247
+ return
248
+ with os.scandir(path) as entries:
249
+ for entry in entries:
250
+ if budget[0] >= stop_at:
251
+ info["limited"] = True
252
+ break
253
+ visit(Path(entry.path), depth + 1)
254
+ except FileNotFoundError:
255
+ info["status"] = "missing" if path == root else "changed_during_read"
256
+ except (OSError, ValueError):
257
+ info["status"] = "unreadable"
258
+
259
+ visit(root, 0)
260
+ return info
261
+
262
+
263
+ def _capabilities(engine: str, observation: dict[str, Any], available: bool) -> dict[str, Any]:
264
+ transcript = _NATIVE | {"t3", "cursor_cli"}
265
+ support = {"requests": transcript | {"cursor"}, "commands": transcript,
266
+ "results": transcript, "outcomes": transcript,
267
+ "usage": _NATIVE | {"t3", "cursor", "cursor_sdk", "cursor_api", "generic_sdk"}}
268
+ return {cap: {
269
+ "support": ("commit_or_pr_links_only" if cap == "outcomes" else
270
+ "native_parser" if engine in transcript else "normalized_parser")
271
+ if engine in support[cap] else "unsupported",
272
+ "observed": (None if not available or observation.get("receipt_status") != "fresh"
273
+ or observation.get("status") != "ok"
274
+ or observation.get("activity_state") == "unknown"
275
+ or engine not in support[cap] else
276
+ bool(observation.get("usage_events")) if cap == "usage" else
277
+ bool(observation.get("human_classifications")) if cap == "requests" else
278
+ None),
279
+ "evidence_scope": ("collector_classifications_not_human_origin_proof" if cap == "requests"
280
+ else "collector_commit_or_pr_links_not_verified_outcomes" if cap == "outcomes"
281
+ else "collector_usage_rows" if cap == "usage"
282
+ else "no_per_capability_evidence_in_scan_receipt"),
283
+ "completeness": "unknown"} for cap in _CAPABILITIES}
284
+
285
+
286
+ def _delivery() -> dict[str, Any]:
287
+ from .push import outbox_path
288
+
289
+ path = outbox_path()
290
+ try:
291
+ if not path.exists():
292
+ return {"status": "available", "pending": {}}
293
+ before = path.stat()
294
+ descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
295
+ with os.fdopen(descriptor, "rb") as handle:
296
+ if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
297
+ return {"status": "unknown", "pending": {}}
298
+ header = handle.read(100)
299
+ sidecars = [path.with_name(path.name + suffix) for suffix in ("-wal", "-shm", "-journal")]
300
+ if (len(header) != 100
301
+ or header[:16] != b"SQLite format 3\x00" or header[18:20] != b"\x01\x01"
302
+ or any(item.exists() for item in sidecars)):
303
+ # shortcut: live or persisted WAL stays unknown until a safe snapshot route exists.
304
+ return {"status": "unknown", "pending": {}}
305
+ with closing(sqlite3.connect(path.resolve().as_uri() + "?mode=ro&immutable=1",
306
+ uri=True, timeout=0.1)) as con:
307
+ con.execute("PRAGMA query_only=ON")
308
+ remaining = [1000]
309
+
310
+ def bounded() -> int:
311
+ remaining[0] -= 1
312
+ return int(remaining[0] <= 0)
313
+
314
+ con.set_progress_handler(bounded, 1000)
315
+ rows = con.execute("SELECT kind, COUNT(*) FROM pending GROUP BY kind LIMIT 16").fetchall()
316
+ after = path.stat()
317
+ identity = ("st_dev", "st_ino", "st_size", "st_mtime_ns", "st_ctime_ns")
318
+ if (any(getattr(before, key) != getattr(after, key) for key in identity)
319
+ or any(item.exists() for item in sidecars)):
320
+ return {"status": "unknown", "pending": {}}
321
+ allowed = {"usage", "session", "activity", "time"}
322
+ if any(kind not in allowed or type(count) is not int or count < 0 for kind, count in rows):
323
+ return {"status": "unknown", "pending": {}}
324
+ return {"status": "available", "pending": dict(rows)}
325
+ except (OSError, sqlite3.Error, ValueError):
326
+ return {"status": "unknown", "pending": {}}
327
+
328
+
329
+ def _publication(declaration: dict[str, str], now: datetime) -> dict[str, Any]:
330
+ result: dict[str, Any] = {"id": declaration["id"], "timezone": declaration["timezone"],
331
+ "status": "unknown", "reason": "receipt_unavailable"}
332
+ try:
333
+ zone = ZoneInfo(declaration["timezone"])
334
+ except (ZoneInfoNotFoundError, ValueError):
335
+ result["reason"] = "invalid_timezone"
336
+ return result
337
+ required = now.astimezone(zone).date() - timedelta(days=1)
338
+ result["required_completed_through"] = required.isoformat()
339
+ status, raw = _read_json(Path(declaration["path"]), 64 * 1024)
340
+ if status != "available":
341
+ result["reason"] = "receipt_" + status
342
+ return result
343
+ verified, published = _stamp(raw.get("verified_at")), _stamp(raw.get("published_at"))
344
+ try:
345
+ completed = date.fromisoformat(raw["completed_through"])
346
+ except (KeyError, ValueError, TypeError):
347
+ result["reason"] = "completed_day_invalid"
348
+ return result
349
+ revision, live = raw.get("published_revision"), raw.get("live_revision")
350
+ if (verified is None or published is None or verified > now or published > now
351
+ or published > verified or completed > required):
352
+ result["reason"] = "receipt_time_invalid"
353
+ elif (not isinstance(revision, str) or not revision or len(revision) > 256
354
+ or not isinstance(live, str) or not live or len(live) > 256):
355
+ result["reason"] = "revision_unverified"
356
+ elif completed != required or now - verified > timedelta(hours=FRESH_HOURS) or revision != live:
357
+ result.update(status="stale", reason="day_revision_or_verification_stale")
358
+ else:
359
+ result.update(status="fresh", reason="local_receipt_verified")
360
+ result["verification_scope"] = "local_receipt_only_no_live_network_check"
361
+ return result
362
+
363
+
364
+ def build_report(cfg: Config, *, now: datetime | None = None) -> dict[str, Any]:
365
+ """Inspect bounded local metadata. Never run collectors, models, delivery or state recovery."""
366
+ from .sources import Registry, SourceError, load_registry
367
+
368
+ now = now or datetime.now(timezone.utc)
369
+ if now.tzinfo is None:
370
+ raise ValueError("coverage time requires a timezone")
371
+ issues: list[dict[str, str]] = []
372
+ try:
373
+ registry = load_registry(cfg.home)
374
+ registry_status = "available"
375
+ except (SourceError, OSError, ValueError):
376
+ registry = Registry((), (), ())
377
+ registry_status = "unreadable"
378
+ _issue(issues, "registry_unreadable", "registry")
379
+ state_status, state = _read_json(state_path(), MAX_STATE_JSON_BYTES)
380
+ watermark = state.get("collectors", {})
381
+ if state_status == "limited":
382
+ _issue(issues, "state_limited", "state")
383
+ watermark = {}
384
+ elif (state_status not in {"available", "missing"} or not isinstance(watermark, dict)
385
+ or state_status == "available" and "collectors" not in state):
386
+ _issue(issues, "state_unreadable", "state")
387
+ watermark = {}
388
+ receipt_status, receipt_data = _read_json(observations_path())
389
+ receipts = receipt_data.get("collectors", {})
390
+ if (receipt_status not in {"available", "missing"} or not isinstance(receipts, dict)
391
+ or receipt_status == "available" and (type(receipt_data.get("version")) is not int
392
+ or receipt_data.get("version") != 1)):
393
+ _issue(issues, "scan_receipts_unreadable", "scan")
394
+ receipts = {}
395
+ budget = [0]
396
+ collectors: list[dict[str, Any]] = []
397
+ all_engines = list(dict.fromkeys((*cfg.agents, "claude_code", "codex", "pi",
398
+ *(s.engine for s in registry.sources))))[:MAX_COLLECTORS]
399
+ planned_roots: dict[str, list[Path]] = {}
400
+ for engine in all_engines:
401
+ try:
402
+ planned_roots[engine] = _roots(cfg, engine)
403
+ except (OSError, ValueError, RuntimeError):
404
+ planned_roots[engine] = []
405
+ _issue(issues, "source_discovery_failed", "collector:" + engine)
406
+ root_count = sum(len(roots) for roots in planned_roots.values())
407
+ root_budget = max(1, MAX_ENTRIES // max(1, root_count))
408
+ for engine in all_engines:
409
+ observation = _receipt(receipts.get(engine), now)
410
+ configured = engine in cfg.agents
411
+ if configured and observation["receipt_status"] != "fresh":
412
+ _issue(issues, "scan_receipt_" + observation["receipt_status"], "collector:" + engine)
413
+ if configured and observation.get("status") not in {None, "ok"}:
414
+ _issue(issues, "collector_failed", "collector:" + engine)
415
+ skipped = observation.get("diagnostics", {}).get("skipped", {})
416
+ if any(skipped.get(k) for k in ("malformed_records", "activity_errors")):
417
+ _issue(issues, "parser_loss", "collector:" + engine)
418
+ if skipped.get("missing_payloads"):
419
+ _issue(issues, "source_payload_missing", "collector:" + engine)
420
+ if skipped.get("unreadable_files"):
421
+ _issue(issues, "source_unreadable", "collector:" + engine)
422
+ clients = observation.get("diagnostics", {}).get("clients", [])
423
+ if any(c.startswith("unknown:") for c in clients):
424
+ _issue(issues, "unattributed_client", "collector:" + engine, "info")
425
+ wm = watermark.get(engine, {})
426
+ files = wm.get("files", {}) if isinstance(wm, dict) else {}
427
+ if not isinstance(wm, dict) or not isinstance(files, dict):
428
+ _issue(issues, "state_unreadable", "collector:" + engine)
429
+ files = files if isinstance(files, dict) else {}
430
+ roots = [_metadata(root, files, budget, engine, root_budget)
431
+ for root in planned_roots[engine]]
432
+ for root in roots:
433
+ if root["limited"]:
434
+ _issue(issues, "discovery_limited", "collector:" + engine)
435
+ if root["status"] not in {"available", "missing", "unknown"}:
436
+ _issue(issues, "source_unreadable", "collector:" + engine)
437
+ if configured and root["unread_bytes"]:
438
+ _issue(issues, "source_byte_backlog", "collector:" + engine)
439
+ collectors.append({"collector": engine, "configured": configured, "roots": roots,
440
+ "observation": observation,
441
+ "capabilities": _capabilities(engine, observation, True)})
442
+ by_engine = {c["collector"]: c for c in collectors}
443
+ sources: list[dict[str, Any]] = []
444
+ declarations: list[dict[str, Any]] = [
445
+ {"id": "native:" + e, "harness": e, "engine": e, "location": "local",
446
+ "home": None, "registered": False, "transport": "native_files"}
447
+ for e in all_engines if e in cfg.agents or e in _NATIVE]
448
+ declarations.extend({"id": s.id, "harness": s.harness, "engine": s.engine,
449
+ "location": s.location, "home": s.home, "registered": True,
450
+ "transport": s.transport}
451
+ for s in registry.sources)
452
+ for declaration in declarations:
453
+ engine = declaration["engine"]
454
+ collector = by_engine.get(engine, {})
455
+ roots = collector.get("roots", [])
456
+ if declaration["home"] is not None:
457
+ home = declaration["home"].resolve()
458
+ roots = [r for r in roots if home == Path(r["path"]).resolve().parent]
459
+ supported = engine in _NATIVE | {"cursor", "cursor_cli", "cursor_sdk", "cursor_api",
460
+ "generic_sdk", "activitywatch", "t3"}
461
+ route_supported = (not declaration["registered"] or engine in _NATIVE
462
+ and declaration["home"] is not None
463
+ and declaration["transport"] in {"native_files", "structured_cli"})
464
+ available = ("unknown" if declaration["location"] == "remote" or not supported
465
+ or not route_supported or not roots
466
+ or any(r["status"] == "unknown" for r in roots) else
467
+ "unreadable" if any(r["status"] not in {"available", "missing"} for r in roots)
468
+ else "available" if any(r["status"] == "available" for r in roots) else "missing")
469
+ if declaration["registered"] and (not supported or not route_supported
470
+ or declaration["location"] == "remote"):
471
+ _issue(issues, "registered_source_unsupported", declaration["id"])
472
+ if declaration["registered"] and available == "unreadable":
473
+ _issue(issues, "source_unreadable", declaration["id"])
474
+ sources.append({k: v for k, v in declaration.items() if k != "home"} | {
475
+ "availability": available, "roots": [r["path"] for r in roots],
476
+ "reason": "host_local_evidence_required" if declaration["location"] == "remote" else
477
+ "no_collector_for_engine" if not supported else
478
+ "declared_transport_not_collected" if not route_supported else
479
+ "metadata_only_no_transcript_read",
480
+ "session_associations": sum(link["source_id"] == declaration["id"] for link in registry.links),
481
+ "capabilities": _capabilities(engine if route_supported else "", {}, False)})
482
+ declared_sources = {source.id: source for source in registry.sources}
483
+ session_links = [{**link, "engine": declared_sources[link["source_id"]].engine,
484
+ "harness": declared_sources[link["source_id"]].harness,
485
+ "association_scope": "declared_not_duplicate_or_human_proof"}
486
+ for link in registry.links[:512]]
487
+ if len(registry.links) > len(session_links):
488
+ _issue(issues, "session_links_limited", "registry", "info")
489
+ publications = [_publication(p, now) for p in registry.publications]
490
+ for publication in publications:
491
+ if publication["status"] != "fresh":
492
+ _issue(issues, "publication_" + publication["status"], publication["id"])
493
+ delivery = _delivery()
494
+ if delivery["status"] == "unknown":
495
+ _issue(issues, "delivery_unknown", "delivery")
496
+ elif sum(delivery["pending"].values()):
497
+ _issue(issues, "delivery_backlog", "delivery")
498
+ catalog_status, catalog = _read_json(
499
+ Path(__file__).with_name("coverage_catalog.json"), 1024 * 1024)
500
+ harnesses = catalog.get("harnesses", [])
501
+ if (catalog_status != "available" or catalog.get("version") != 1
502
+ or not isinstance(harnesses, list) or len(harnesses) > 128
503
+ or any(not isinstance(entry, dict) for entry in harnesses)):
504
+ harnesses = []
505
+ _issue(issues, "catalog_unavailable", "catalog", "info")
506
+ from .harness_inventory import discover
507
+ agents = frozenset(cfg.agents)
508
+ # The t3 collector refuses to read without its cutover, so it qualifies nothing until set.
509
+ readers = agents if cfg.t3_activity_since else agents - {"t3"}
510
+ inventory = discover(cfg.home, harnesses, readers=readers)
511
+ if inventory["status"] == "limited":
512
+ _issue(issues, "harness_inventory_limited", "inventory", "info")
513
+ wraps = {entry.get("id"): entry.get("wraps") for entry in harnesses}
514
+ for candidate in inventory["observations"]:
515
+ harness = candidate["harness_id"]
516
+ if candidate["reader_qualified"]:
517
+ continue
518
+ if candidate["activity"] != "recent":
519
+ _issue(issues, "harness_route_unverified", harness, "info")
520
+ elif isinstance(wraps.get(harness), list) and agents & set(wraps[harness]):
521
+ # It drives native CLIs whose logs AUT reads: the work is counted, only not attributed.
522
+ _issue(issues, "harness_unattributed", harness, "info")
523
+ else:
524
+ _issue(issues, "harness_active_unread", harness)
525
+ return {"version": 1, "generated_at": now.isoformat(), "completeness": "unknown",
526
+ "thresholds": {"collector_evidence_hours": FRESH_HOURS,
527
+ "publication_verification_hours": FRESH_HOURS},
528
+ "state_status": state_status,
529
+ "read_limits": {"json_bytes": MAX_JSON_BYTES, "state_json_bytes": MAX_STATE_JSON_BYTES,
530
+ "metadata_entries": MAX_ENTRIES,
531
+ "metadata_entries_per_root": root_budget,
532
+ "metadata_depth": MAX_DEPTH, "metadata_entries_visited": budget[0]},
533
+ "registry_status": registry_status, "sources": sources, "collectors": collectors,
534
+ "session_links": session_links, "session_links_omitted": len(registry.links) - len(session_links),
535
+ "publications": publications, "delivery": delivery, "issues": issues,
536
+ "catalog": harnesses, "harness_inventory": inventory}
537
+
538
+
539
+ ALERT_HOURS = 24
540
+ ALERT_FORGET_DAYS = 7
541
+ # degraded pages only with the homelab `agent coverage` rule; "error" pages through the
542
+ # existing rule after 3 scans.
543
+ ALERT_STATUS: Final = "degraded"
544
+ _ALERT_PHRASES = {
545
+ "harness_active_unread": "%s harness active, no AUT reader",
546
+ "discovery_limited": "%s discovery limited",
547
+ "source_payload_missing": "%s payloads missing",
548
+ "parser_loss": "%s parser loss",
549
+ "source_unreadable": "%s source unreadable",
550
+ }
551
+
552
+
553
+ def alert_state(report: dict[str, Any], previous: dict[str, Any], now: datetime, *,
554
+ previous_status: str = "available") -> tuple[dict[str, dict[str, str]], str | None]:
555
+ """Carry per-issue alert state and return it with the text of the issues that are new.
556
+ An actionable warning alerts for ALERT_HOURS after it first appears, then it is known.
557
+ A key absent for ALERT_FORGET_DAYS is forgotten, so flapping issues do not page again.
558
+ The text holds fixed phrases and source ids only, never paths."""
559
+ prior = previous.get("alerts")
560
+ # The first report after an install or upgrade knows today's issues. A damaged previous file
561
+ # is not a first report, so its issues still alert.
562
+ baseline = not isinstance(prior, dict) and previous_status in {"available", "missing"}
563
+ prior = prior if isinstance(prior, dict) else {}
564
+ forget = timedelta(days=ALERT_FORGET_DAYS)
565
+
566
+ def live(entry: object) -> dict[str, Any] | None:
567
+ last = _stamp(entry.get("last_seen")) if isinstance(entry, dict) else None
568
+ return entry if isinstance(entry, dict) and last and now - last < forget else None
569
+
570
+ current = sorted({f"{i['code']}:{i['source_id']}" for i in report.get("issues", [])
571
+ if isinstance(i, dict) and i.get("code") in _ALERT_PHRASES
572
+ and i.get("severity") != "info" and isinstance(i.get("source_id"), str)})
573
+ # An absent key keeps its entry for a week, marked with when it went away.
574
+ alerts = {key: {**entry, "absent_since": entry.get("absent_since") or now.isoformat()}
575
+ for key, entry in prior.items() if key not in current and live(entry)}
576
+ start = now - timedelta(hours=ALERT_HOURS) if baseline else now
577
+ for key in current:
578
+ # A key the last report still showed keeps its first sighting across a scan gap.
579
+ # One the last report showed absent starts again once its retained entry has expired.
580
+ entry = prior.get(key)
581
+ if isinstance(entry, dict) and entry.get("absent_since") and not live(entry):
582
+ entry = None
583
+ first = _stamp(entry.get("first_seen")) if isinstance(entry, dict) else None
584
+ alerts[key] = {"first_seen": (first or start).isoformat(), "last_seen": now.isoformat()}
585
+ new = [key for key in current
586
+ if now - (_stamp(alerts[key]["first_seen"]) or now) < timedelta(hours=ALERT_HOURS)]
587
+ if not new:
588
+ return alerts, None
589
+ phrases = []
590
+ for key in new:
591
+ code, _, source = key.partition(":")
592
+ phrases.append(_ALERT_PHRASES[code] % source.removeprefix("collector:"))
593
+ return alerts, ("new: " + "; ".join(phrases))[:300]
594
+
595
+
596
+ def save_report(report: dict[str, Any]) -> tuple[bool, str | None] | None:
597
+ """Merge alert state from the previous assessment and keep this one, both under the report
598
+ lock, so overlapping scans cannot lose each other's alerts. Returns (issue set changed,
599
+ new-alert text), or None when a newer assessment is already saved."""
600
+ signature = hashlib.sha256(json.dumps(sorted(
601
+ (str(i.get("code", "")), str(i.get("source_id", "")), str(i.get("severity", "")))
602
+ for i in report.get("issues", []) if isinstance(i, dict))).encode()).hexdigest()
603
+ path = report_path()
604
+ with _locked(path):
605
+ status, previous = _read_json(path)
606
+ previous_at = _stamp(previous.get("generated_at"))
607
+ incoming_at = _stamp(report.get("generated_at"))
608
+ if (previous_at and previous_at <= datetime.now(timezone.utc)
609
+ and (incoming_at is None or previous_at > incoming_at)):
610
+ return None
611
+ report["alerts"], alert = alert_state(report, previous,
612
+ incoming_at or datetime.now(timezone.utc),
613
+ previous_status=status)
614
+ atomic_write_text(path, json.dumps({**report, "issue_signature": signature}, sort_keys=True))
615
+ return previous.get("issue_signature") != signature, alert