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,310 @@
1
+ """Shared collector helpers: inode-aware byte-offset JSONL tailing + small normalizers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import os
7
+ import sys
8
+ from collections import Counter
9
+ from contextlib import contextmanager
10
+ from contextvars import ContextVar
11
+ from dataclasses import dataclass, field
12
+ from datetime import datetime, timezone
13
+ from typing import Any, Callable, Iterable, Iterator, Sequence
14
+
15
+ from ..event import Batch, CollectorUnavailable, Row
16
+ from ..diagnostics import note_skips
17
+
18
+ # Cap lines read per file per scan so a huge first-scan/backfill file can't spike memory.
19
+ # The offset is committed at the cap, so the next scan simply continues from there.
20
+ _MAX_LINES = 50000
21
+ MS_PER_S = 1000
22
+ # What a malformed log record can raise while it is read. OverflowError: int(inf) from a 1e400.
23
+ MALFORMED_RECORD = (KeyError, TypeError, ValueError, AttributeError, OverflowError)
24
+
25
+
26
+ @dataclass
27
+ class FileSnapshot:
28
+ """Finish admitted history even when native files keep growing."""
29
+ bounds: dict[str, tuple[int, int]] = field(default_factory=dict)
30
+ frozen: bool = False
31
+ deferred: dict[str, dict[str, Any]] = field(default_factory=dict)
32
+
33
+ def restart_deferred(self) -> None:
34
+ # A truncated file can remain as long as its old offset; force a fresh read next run.
35
+ for path, files in self.deferred.items():
36
+ files.pop(path, None)
37
+
38
+
39
+ _SNAPSHOT: ContextVar[FileSnapshot | None] = ContextVar("native_file_snapshot", default=None)
40
+
41
+
42
+ @contextmanager
43
+ def file_snapshot(snapshot: FileSnapshot) -> Iterator[None]:
44
+ token = _SNAPSHOT.set(snapshot)
45
+ try:
46
+ yield
47
+ finally:
48
+ _SNAPSHOT.reset(token)
49
+
50
+
51
+ class _SnapshotChanged(Exception):
52
+ """The admitted file generation vanished before its bounded read completed."""
53
+
54
+
55
+ def describe_files(cfg: object, wm: dict[str, Any]) -> str:
56
+ """`aut status` line of a collector whose watermark tracks files."""
57
+ return f"{len(wm['files'])} files tracked" if "files" in wm else "never scanned"
58
+
59
+
60
+ def describe_full_scan(cfg: object, wm: dict[str, Any]) -> str:
61
+ """`aut status` line of a collector that keeps no watermark."""
62
+ return "full-scan each run (no watermark)"
63
+
64
+
65
+ def str_or_none(value: object) -> str | None:
66
+ """A non-empty string as is; anything else is None."""
67
+ return value if isinstance(value, str) and value else None
68
+
69
+
70
+ def dict_or_empty(value: object) -> dict[str, Any]:
71
+ """A dict as is; anything else is {}, for an untrusted nested object in a log record."""
72
+ return value if isinstance(value, dict) else {}
73
+
74
+
75
+ def safe_int(value: object, default: int = 0) -> int:
76
+ """Non-negative int() that never raises, for untrusted counts, offsets and timestamps from
77
+ logs and state. A negative or unparseable value becomes `default`: a corrupt state offset
78
+ (1e400 -> inf -> OverflowError, or a negative one, which would make fh.seek() raise) must not
79
+ wedge the scan."""
80
+ if not isinstance(value, (int, float, str)):
81
+ return default
82
+ try:
83
+ parsed = int(value)
84
+ except (ValueError, OverflowError):
85
+ return default
86
+ return parsed if parsed >= 0 else default
87
+
88
+
89
+ def count_field(record: dict[str, Any], key: str) -> int:
90
+ """A token count from a log record; absent or null is 0. Raises on a malformed one, which the
91
+ caller counts as a malformed record."""
92
+ return int(record.get(key) or 0)
93
+
94
+
95
+ def noop_advance() -> None:
96
+ """The watermark callback of a full-scan collector: it has no watermark to advance."""
97
+
98
+
99
+ def warn_skipped(name: str, skipped: Counter[str], unaffected: str = "usage") -> None:
100
+ """Report a collector's skips. Skipping is best effort on purpose: a failed activity extraction
101
+ never blocks the usage and session rows of the same chunk, and one bad record never wedges a
102
+ scan at its offset. But a malformed usage record's tokens are gone, so neither stays silent.
103
+ Activity failures are keyed "activity:<exception type>": the type names a systematic parser
104
+ break and, unlike a message, cannot carry record content."""
105
+ note_skips(skipped)
106
+ failed = {k.partition(":")[2]: n for k, n in sorted(skipped.items())
107
+ if k.startswith("activity:") and n}
108
+ if failed:
109
+ print(f"aut: {name}: {sum(failed.values())} activity record(s) skipped (extraction failed: "
110
+ f"{', '.join(f'{k} x{n}' for k, n in failed.items())}); "
111
+ f"{unaffected} and session rows are unaffected.", file=sys.stderr)
112
+ if skipped["missing_payloads"]:
113
+ print(f"aut: {name}: {skipped['missing_payloads']} record(s) have no stored payload; "
114
+ "source coverage remains incomplete.", file=sys.stderr)
115
+ if skipped["malformed"]:
116
+ print(f"aut: {name}: {skipped['malformed']} malformed record(s) skipped; any usage they "
117
+ "held is not counted.", file=sys.stderr)
118
+
119
+
120
+ def raise_if_unreadable(name: str, skipped: Counter[str]) -> None:
121
+ """After a collector's last batch: files that are there but could not be read make the scan
122
+ degraded instead of looking like files with nothing new."""
123
+ if skipped["unreadable"]:
124
+ raise CollectorUnavailable(f"{name}: {skipped['unreadable']} file(s) could not be read, "
125
+ "left for the next scan")
126
+
127
+
128
+ def read_new_lines(path: str, offset: int, *, end_offset: int | None = None,
129
+ ) -> tuple[list[bytes], int]:
130
+ """Stream complete newline-terminated records added after `offset` (capped at _MAX_LINES).
131
+
132
+ Iterates one line at a time, through end_offset when supplied, and stops at a trailing partial line
133
+ (no newline yet), leaving it for the next scan. Returns (complete_lines, new_offset). A file
134
+ that vanished has nothing new; any other OSError (no permission, a failing disk) is the
135
+ caller's to report.
136
+ """
137
+ lines: list[bytes] = []
138
+ consumed = offset
139
+ try:
140
+ with open(path, "rb") as fh:
141
+ snapshot = _SNAPSHOT.get()
142
+ expected = snapshot.bounds.get(path) if snapshot else None
143
+ if expected:
144
+ st = os.fstat(fh.fileno())
145
+ if st.st_ino != expected[0] or st.st_size < expected[1]:
146
+ raise _SnapshotChanged
147
+ fh.seek(offset)
148
+ while end_offset is None or consumed < end_offset:
149
+ raw = fh.readline(-1 if end_offset is None else end_offset - consumed)
150
+ if not raw:
151
+ break
152
+ if raw.endswith(b"\n"):
153
+ lines.append(raw)
154
+ consumed += len(raw)
155
+ if len(lines) >= _MAX_LINES:
156
+ break # commit here; next scan continues from `consumed`
157
+ else:
158
+ break # trailing partial line at EOF; picked up whole next time
159
+ if expected and os.fstat(fh.fileno()).st_size < expected[1]:
160
+ raise _SnapshotChanged
161
+ except FileNotFoundError:
162
+ return [], offset # gone now; leave the offset put
163
+ return lines, consumed
164
+
165
+
166
+ def same_file(fstate: dict[str, Any], st: os.stat_result) -> bool:
167
+ """May a tail resume from this watermark entry? False on first sight (empty entry), when the
168
+ file behind the path changed (rotated/replaced), and when it was truncated in place, so the
169
+ beginning of a replacement is never skipped.
170
+
171
+ Identity is st_ino ALONE, deliberately not (st_dev, st_ino). st_dev is assigned at mount,
172
+ not intrinsic to the volume: macOS/APFS hands out a different number after every reboot. Any
173
+ watermark holding st_dev therefore goes stale on restart, every tracked path looks replaced,
174
+ and the whole history is re-read and re-pushed. (Idempotent at the sink, but on a heavy
175
+ machine that is a multi-minute scan and ~500k redundant rows per reboot.)
176
+
177
+ What dropping it costs: an inode is only unique within a device, so a path that migrates to
178
+ another filesystem could collide with a same-numbered inode there and be resumed mid-file.
179
+ That needs a tracked path to change volumes AND collide, and it undercounts rather than
180
+ double-counts. A guaranteed re-push every reboot is the worse trade. Entries saved by older
181
+ versions still hold a `dev` key; nothing reads it."""
182
+ return fstate.get("ino") == st.st_ino and st.st_size >= safe_int(fstate.get("off"))
183
+
184
+
185
+ def changed_files(paths: Iterable[str], files: dict[str, Any], fresh: Callable[[os.stat_result], Any],
186
+ skipped: Counter[str], revisit: Callable[[Any], bool] | None = None,
187
+ ) -> Iterator[tuple[str, Any, int, list[bytes], int]]:
188
+ """Each file of `paths` with something to do: (path, private copy of its entry in `files`,
189
+ offset read from, complete new lines, new offset). That is a file with bytes past its entry,
190
+ one whose entry must restart (replaced or truncated: an offset left standing would skip bytes
191
+ if it regrew past it), and one whose entry `revisit` wants looked at with no new bytes.
192
+ `fresh(st)` is the entry of a file seen for the first time or replaced. The copy is deep so
193
+ that only the caller's watermark callback can publish a chunk's state. A file that cannot be
194
+ read is counted in skipped["unreadable"]."""
195
+ snapshot = _SNAPSHOT.get()
196
+ for path in paths:
197
+ end_offset = None
198
+ if snapshot:
199
+ if path in snapshot.deferred or (snapshot.frozen and path not in snapshot.bounds):
200
+ continue
201
+ bound = snapshot.bounds.get(path)
202
+ entry = files.get(path) or {}
203
+ if (bound and snapshot.frozen and safe_int(entry.get("off")) >= bound[1]
204
+ and not (revisit and revisit(entry))):
205
+ continue
206
+ try:
207
+ st = os.stat(path)
208
+ if snapshot:
209
+ bound = snapshot.bounds.setdefault(path, (st.st_ino, st.st_size))
210
+ if st.st_ino != bound[0] or st.st_size < bound[1]:
211
+ snapshot.deferred[path] = files
212
+ continue
213
+ end_offset = bound[1]
214
+ entry = files.get(path) or {}
215
+ restart = bool(entry) and not same_file(entry, st)
216
+ prev = fresh(st) if restart or not entry else entry
217
+ off = safe_int(prev.get("off"))
218
+ size = st.st_size if end_offset is None else end_offset
219
+ if size <= off and not restart and not (revisit and revisit(prev)):
220
+ continue
221
+ lines, new_off = (read_new_lines(path, off) if end_offset is None else
222
+ read_new_lines(path, off, end_offset=end_offset))
223
+ except _SnapshotChanged:
224
+ assert snapshot is not None
225
+ snapshot.deferred[path] = files
226
+ continue
227
+ except FileNotFoundError: # gone since the glob: nothing to read, and no offset to lose
228
+ continue
229
+ except OSError:
230
+ skipped["unreadable"] += 1
231
+ continue
232
+ yield path, copy.deepcopy(prev), off, lines, new_off
233
+
234
+
235
+ def file_batches(name: str, paths: Iterable[str], files: dict[str, Any],
236
+ fresh: Callable[[os.stat_result], Any],
237
+ chunk_rows: Callable[[str, Any, int, list[bytes], Counter[str]], Sequence[Row]],
238
+ revisit: Callable[[Any], bool] | None = None) -> Iterator[Batch]:
239
+ """A tailing collector's batches over changed_files. `chunk_rows(path, cur, off, lines, skipped)`
240
+ makes one file's rows and updates `cur`, the private copy of its entry, whose "off" already
241
+ holds the new offset; the entry is published only when the batch's callback runs."""
242
+ skipped: Counter[str] = Counter()
243
+ for path, cur, off, lines, new_off in changed_files(paths, files, fresh, skipped, revisit):
244
+ cur["off"] = new_off
245
+ events = chunk_rows(path, cur, off, lines, skipped)
246
+
247
+ def advance_watermark(p: str = path, c: dict[str, Any] = cur) -> None:
248
+ files[p] = c
249
+
250
+ yield events, advance_watermark
251
+ warn_skipped(name, skipped)
252
+ raise_if_unreadable(name, skipped)
253
+
254
+
255
+ def _strip_worktree(parts: list[str]) -> list[str] | None:
256
+ """Rewrite a git-worktree checkout path to the equivalent path in its MAIN checkout.
257
+
258
+ Without this every worktree becomes its own `project`: one repo worked on across 50 branches
259
+ reports as 50 projects and no per-project total is real. A worktree IS the same repo, so
260
+ `<repo>/<container>/<branch>/sub` normalizes to `<repo>/sub` -- which also keeps a monorepo's
261
+ inner package attributed to that package rather than to the branch it was checked out on.
262
+
263
+ Git puts a worktree wherever you point it, so no rule catches every layout. These are the two
264
+ conventional ones, and both require a DOT-directory, so an ordinary project folder can never
265
+ trip this:
266
+
267
+ <repo>/.claude/worktrees/<branch>/... Claude Code's own layout (a `worktrees` dir
268
+ inside any dot-directory)
269
+ <repo>/.worktrees/<branch>/... the common hand-rolled form (any dot-directory
270
+ whose name ends in `worktrees`, so
271
+ `.claude-worktrees` matches too)
272
+
273
+ Anything else (`git worktree add ../repo-wt`) is indistinguishable from a sibling repo by
274
+ path alone, so it is left as-is. Returns None when there is nothing to rewrite."""
275
+ for i, seg in enumerate(parts):
276
+ if not seg.startswith("."):
277
+ continue
278
+ if seg.lower().endswith("worktrees"):
279
+ drop = 2 # .worktrees/<branch>
280
+ elif i + 1 < len(parts) and parts[i + 1].lower() == "worktrees":
281
+ drop = 3 # .claude/worktrees/<branch>
282
+ else:
283
+ continue
284
+ if i + drop > len(parts): # the container itself, no branch under it -> leave alone
285
+ return None
286
+ return parts[:i] + parts[i + drop:]
287
+ return None
288
+
289
+
290
+ def project_name(path: object) -> str | None:
291
+ """Last path segment only (never a full path -> safe for a public-later repo), after
292
+ collapsing a git worktree back onto its main checkout (see _strip_worktree). Handles BOTH
293
+ '/' and '\\' so a Windows path is reduced on POSIX too; rejects non-strings (returns None)
294
+ so a stray list/dict can't be str()-leaked as a 'project'."""
295
+ if not isinstance(path, str) or not path:
296
+ return None
297
+ seg = path.rstrip("/\\").replace("\\", "/")
298
+ rewritten = _strip_worktree(seg.split("/"))
299
+ if rewritten and any(rewritten): # all-empty == the path was ONLY a container; keep it
300
+ seg = "/".join(rewritten)
301
+ return seg.rsplit("/", 1)[-1] or None
302
+
303
+
304
+ def epoch_ms_to_iso(ms: object) -> str | None:
305
+ if not isinstance(ms, (int, float, str)):
306
+ return None
307
+ try:
308
+ return datetime.fromtimestamp(float(ms) / MS_PER_S, tz=timezone.utc).isoformat()
309
+ except (ValueError, OSError, OverflowError):
310
+ return None
@@ -0,0 +1,294 @@
1
+ """What the activity extractors share: the per-turn tool aggregates, the per-turn link fields and
2
+ small record helpers. Commit detection lives in commits.py. attrs built from these carry counts,
3
+ flags, short enums and hashes only.
4
+
5
+ The turn aggregates' retry and runaway rules are ported from AgentsView
6
+ (github.com/kenn-io/agentsview, MIT licence, (c) its authors).
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import hashlib
12
+ import json
13
+ import re
14
+ from collections import Counter
15
+ from datetime import datetime
16
+ from typing import Any, Callable, NotRequired, TypedDict, TypeVar
17
+
18
+ from ..event import EventSession, RunOrigin, UsageEvent, make_event_id
19
+ from ..repo_keys import RepoKeys, repo_identity
20
+ from ._util import MS_PER_S
21
+ from .commits import COMMIT_LINE, commit_repo
22
+
23
+ _T = TypeVar("_T")
24
+ _HEX_SHA = re.compile(r"[0-9a-f]{7,40}")
25
+ # link fields: a commit-like SHA (7 to 40 hex, not inside a longer word, a uuid or a 64-hex hash),
26
+ # a strict ticket id, a GitHub or Bitbucket PR URL
27
+ _SHA_REF = re.compile(r"(?<![\w-])[0-9a-f]{7,40}(?![\w-])")
28
+ _TICKET = re.compile(r"(?<![A-Za-z0-9])[A-Z][A-Z0-9]{1,9}-\d+(?![A-Za-z0-9])")
29
+ _NOT_TICKET = {"UTF", "SHA", "ISO", "RFC", "CVE", "PEP", "HTTP", "TLS", "SSL", "WCAG"}
30
+ _PR_URL = re.compile(r"https?://(?:www\.)?(?:(github\.com)/([\w.-]+)/([\w.-]+)/pull"
31
+ r"|(bitbucket\.org)/([\w.-]+)/([\w.-]+)/pull-requests)/(\d+)")
32
+ _DEFAULT_BRANCHES = {"main", "master", "develop", "trunk", "HEAD"}
33
+ # 20 SHAs (first come) filled up on 7% of Claude Code and 26% of Cursor turns that quote any,
34
+ # pushing out a commit quoted late in the turn; 50 is cheap at one key each
35
+ MAX_SHAS, MAX_PRS, MAX_TICKETS = 50, 10, 5
36
+ IDLE_S = 3600 # a file untouched this long is complete: its open link turn closes
37
+
38
+
39
+ def text_of(content: object) -> str:
40
+ """A message's text: the string itself, or its text blocks joined."""
41
+ if isinstance(content, str):
42
+ return content
43
+ if isinstance(content, list):
44
+ return "\n".join(b["text"] for b in content if isinstance(b, dict)
45
+ and b.get("type") == "text" and isinstance(b.get("text"), str))
46
+ return ""
47
+
48
+
49
+ def tool_key(name: str) -> str:
50
+ """MCP tools are `mcp__<server>__<tool>`, and a server label is free text (it can name an
51
+ employer or client), so they all count as `mcp`."""
52
+ return "mcp" if name.startswith("mcp__") else name
53
+
54
+
55
+ def text_sha256(text: str) -> str:
56
+ """Hex SHA-256 of the stripped text."""
57
+ return hashlib.sha256(text.strip().encode("utf-8")).hexdigest()
58
+
59
+
60
+ def ms_between(start: object, end: object) -> int | None:
61
+ """Milliseconds from one ISO-8601 timestamp to another; None when either is unusable."""
62
+ try:
63
+ a = datetime.fromisoformat(str(start).replace("Z", "+00:00"))
64
+ b = datetime.fromisoformat(str(end).replace("Z", "+00:00"))
65
+ return int((b - a).total_seconds() * MS_PER_S)
66
+ except (TypeError, ValueError):
67
+ return None
68
+
69
+
70
+ def first_record(path: str) -> dict[str, Any] | None:
71
+ """The file's first JSON line, for a header a resumed scan no longer reads."""
72
+ try:
73
+ with open(path, "rb") as fh:
74
+ o = json.loads(fh.readline())
75
+ except (OSError, ValueError):
76
+ return None
77
+ return o if isinstance(o, dict) else None
78
+
79
+
80
+ def branch_key(keys: RepoKeys, repo_key: str | None, branch: object) -> str | None:
81
+ """HMAC(repo_key || branch) for a non-default branch; a branch name is never stored."""
82
+ if not repo_key or not isinstance(branch, str) or not branch \
83
+ or branch in _DEFAULT_BRANCHES:
84
+ return None
85
+ return keys.of(repo_key + branch)
86
+
87
+
88
+ def pr_key(keys: RepoKeys, host: str, repo: str, number: object) -> str | None:
89
+ try:
90
+ identity = repo_identity(f"https://{host}/{repo.strip('/')}")
91
+ except ValueError:
92
+ return None
93
+ return keys.of(f"{identity}|{number}")
94
+
95
+
96
+ def sha_key(keys: RepoKeys, sha: str) -> str | None:
97
+ """HMAC of a SHA's first 7 hex: a quoted SHA and a printed commit meet on it, and a hex secret
98
+ that passes the SHA filter (a 32-hex API key, a 40-hex token) is never kept, not even a
99
+ prefix of it. None without a salt, and None for anything that is not 7 to 40 hex (a structured
100
+ sha of '1' would otherwise key every session that printed it into one episode)."""
101
+ sha = sha.lower()
102
+ return keys.of("sha7:" + sha[:7]) if _HEX_SHA.fullmatch(sha) else None
103
+
104
+
105
+ class Link:
106
+ """One turn's link fields (activity kind `link`). The state dict `s` is mutated in place and
107
+ rides in the watermark, so it holds keys only, never a SHA, branch, ticket, URL or path.
108
+ s["at"]: source rank -> [repo_key, branch_key]; rank 0 the commit (`[branch sha]` line and the
109
+ commit's own directory), 1 the worktree, 2 the session meta (Codex git), 3 the record.
110
+ branch_key is False where the source names a default branch: it has no key, and a lower rank
111
+ may not stand in for it."""
112
+
113
+ def __init__(self, keys: RepoKeys, s: dict[str, Any]) -> None:
114
+ self.keys, self.s = keys, s
115
+
116
+ def source(self, repo_key: str | None, branch: object = None) -> list[str | bool | None]:
117
+ """[repo_key, branch_key] of one source (its branch's tickets go to this turn)."""
118
+ self.note_tickets(branch)
119
+ named = repo_key and isinstance(branch, str) and branch in _DEFAULT_BRANCHES
120
+ return [repo_key, False if named else branch_key(self.keys, repo_key, branch)]
121
+
122
+ def place(self, rank: int, repo_key: str | None, branch: object = None) -> None:
123
+ self.s.setdefault("at", {})[str(rank)] = self.source(repo_key, branch)
124
+
125
+ def _add(self, field: str, value: str | None, cap: int) -> bool:
126
+ got = self.s.setdefault(field, [])
127
+ if value and value not in got and len(got) < cap:
128
+ got.append(value)
129
+ return len(got) < cap
130
+
131
+ def note_tickets(self, text: object) -> None:
132
+ if isinstance(text, str) and "-" in text:
133
+ for m in _TICKET.finditer(text):
134
+ if m[0].split("-")[0] not in _NOT_TICKET \
135
+ and not self._add("tix", self.keys.of(m[0]), MAX_TICKETS):
136
+ break
137
+
138
+ def note_commit(self, repo_key: str | None, text: str, shas: list[str]) -> None:
139
+ """A commit call's output: its repo, the commits it printed (`commit_shas`), and the
140
+ branch and subject of git's commit line."""
141
+ for sha in shas:
142
+ self._add("cks", sha_key(self.keys, sha), MAX_SHAS)
143
+ m = COMMIT_LINE.search(text)
144
+ self.place(0, repo_key, m["br"] if m else None)
145
+ for m in COMMIT_LINE.finditer(text):
146
+ self.note_tickets(m["subj"])
147
+
148
+ def note_text(self, text: object) -> None:
149
+ """Tool output or message text: SHAs it quotes and the PRs it links."""
150
+ if not isinstance(text, str):
151
+ return
152
+ if len(self.s.get("shas", ())) < MAX_SHAS:
153
+ for m in _SHA_REF.finditer(text):
154
+ v = m[0]
155
+ if not v.isdigit() and not v.isalpha() \
156
+ and not self._add("shas", sha_key(self.keys, v), MAX_SHAS):
157
+ break
158
+ if "/pull" in text and len(self.s.get("prs", ())) < MAX_PRS:
159
+ for m in _PR_URL.finditer(text):
160
+ host, o, r = (m[1], m[2], m[3]) if m[1] else (m[4], m[5], m[6])
161
+ if not self._add("prs", pr_key(self.keys, host, f"{o}/{r}", int(m[7])), MAX_PRS):
162
+ break
163
+
164
+ def note_pr(self, host: str, repo: object, number: object) -> None:
165
+ if host and isinstance(repo, str):
166
+ self._add("prs", pr_key(self.keys, host, repo, number), MAX_PRS)
167
+
168
+ def attrs(self, origin: RunOrigin) -> dict[str, Any]:
169
+ at = [self.s["at"][k] for k in sorted(self.s.get("at", {}))]
170
+ # the repo of the first source that has one; its branch from that source, or from a lower
171
+ # one in the SAME repo (a branch edge must never join two repos)
172
+ rk = next((r for r, _b in at if r), None)
173
+ bk = next((b for r, b in at if r == rk and b is not None), None) if rk else None
174
+ return {"repo_key": rk, "branch_key": bk or None,
175
+ "ticket_keys": list(self.s.get("tix", ())), "sha_refs": list(self.s.get("shas", ())),
176
+ "commit_keys": list(self.s.get("cks", ())), "pr_keys": list(self.s.get("prs", ())),
177
+ # subagents and scripted runs attach to an episode, never start one
178
+ "role": "child" if origin in ("subagent", "automated") else "seed"}
179
+
180
+ def merge(self, other: dict[str, Any]) -> None:
181
+ """Add a session-level source (ranks it lacks, its tickets) to this turn."""
182
+ for k, v in (other.get("at") or {}).items():
183
+ self.s.setdefault("at", {}).setdefault(k, v)
184
+ for t in other.get("tix") or ():
185
+ self._add("tix", t, MAX_TICKETS)
186
+
187
+ def reset(self) -> None:
188
+ self.s.clear()
189
+
190
+
191
+ def record_commits(link: Link, cwd: object, target: object, text: str, shas: list[str], *,
192
+ amend: bool, fallback: str | None = None) -> list[tuple[str, dict[str, Any]]]:
193
+ """Tell the turn's link about a commit call's printed `shas`; (sha, attrs) of each commit row."""
194
+ if not shas:
195
+ return []
196
+ key = commit_repo(link.keys, cwd, target, fallback)
197
+ link.note_commit(key, text, shas)
198
+ return [(sha, {"sha": sha, "repo_key": key, "amend": amend}) for sha in shas]
199
+
200
+
201
+ def pad_pending(act: dict[str, Any] | None) -> None:
202
+ """State upgrade: a pending commit call saved before its target was kept gains target None."""
203
+ for call in ((act or {}).get("pend") or {}).values():
204
+ call[2:] = call[2:] or [None]
205
+
206
+
207
+ def drop_raw_shas(act: dict[str, Any] | None) -> None:
208
+ """State upgrade: a link saved before sha_refs were keyed held raw hex; only the keys stay."""
209
+ link = (act or {}).get("link") or {}
210
+ if link.get("shas"):
211
+ link["shas"] = [v for v in link["shas"] if len(v) == 64]
212
+
213
+
214
+ def pop_pending(pend: dict[str, Any], tid: str) -> tuple[bool, bool, object]:
215
+ """Take one pending commit call. It rides in the watermark as the JSON list
216
+ [is_amend, printed_before, target]; this is the one place that knows the order."""
217
+ amend, before, target = pend.pop(tid)
218
+ return bool(amend), bool(before), target
219
+
220
+
221
+ def best_effort(errors: Counter[str], fn: Callable[..., _T], *args: object) -> _T | None:
222
+ """Run one activity step. One that raises is counted by exception type and skipped (None), so
223
+ activity can never block the usage and session rows of the same chunk."""
224
+ try:
225
+ return fn(*args)
226
+ except Exception as exc:
227
+ errors[f"activity:{type(exc).__name__}"] += 1
228
+ return None
229
+
230
+
231
+ def human_event(agent: str, id_parts: tuple[Any, ...], ts: str | None, session: EventSession | None = None,
232
+ project: str | None = None) -> UsageEvent:
233
+ """The zero-token usage row of a prompt a person typed."""
234
+ return UsageEvent(event_id=make_event_id(agent, "human", *id_parts), ts=ts, agent=agent,
235
+ model=None, provider=None, kind="human", project=project, session=session)
236
+
237
+
238
+ class TurnAgg(TypedDict):
239
+ """One turn's tool aggregates. A plain dict because it rides in the watermark as JSON."""
240
+ calls: int
241
+ errors: int
242
+ hooks: int
243
+ by: dict[str, int]
244
+ last: str | None # the previous call's tool and input hash
245
+ run: int # length of the current run of identical calls
246
+ max: int # longest such run
247
+ mcp_ids: NotRequired[list[Any]] # codex: MCP call ids, to match the item Desktop logs again
248
+ error_ids: NotRequired[list[str]]
249
+
250
+
251
+ def blank_tool_tally() -> TurnAgg:
252
+ return {"calls": 0, "errors": 0, "hooks": 0, "by": {}, "last": None, "run": 0, "max": 0}
253
+
254
+
255
+ def result_status(value: object, error: object = None) -> str:
256
+ """A missing result status is unknown, not evidence that a command worked."""
257
+ if error is True:
258
+ return "error"
259
+ parsed: Any = value
260
+ if isinstance(value, str):
261
+ try:
262
+ parsed = json.loads(value)
263
+ except ValueError:
264
+ match = re.search(r"^Process exited with code (-?\d+)\s*$", value, re.M)
265
+ if match:
266
+ return "success" if int(match[1]) == 0 else "error"
267
+ if isinstance(parsed, dict):
268
+ code = parsed.get("exit_code")
269
+ if type(code) is int:
270
+ return "success" if code == 0 else "error"
271
+ if parsed.get("isError") is True:
272
+ return "error"
273
+ return "success" if error is False else "unknown"
274
+
275
+
276
+ def add_call(agg: TurnAgg, name: str, args: object) -> None:
277
+ """Count one tool call; a run of the same tool with the same input feeds max_identical_run."""
278
+ agg["calls"] += 1
279
+ agg["by"][tool_key(name)] = agg["by"].get(tool_key(name), 0) + 1
280
+ key = name + ":" + text_sha256(json.dumps(args, sort_keys=True, default=str))[:16]
281
+ agg["run"] = agg["run"] + 1 if key == agg["last"] else 1
282
+ agg["last"], agg["max"] = key, max(agg["max"], agg["run"])
283
+
284
+
285
+ def turn_attrs(agg: TurnAgg) -> dict[str, Any]:
286
+ top = max(agg["by"].values(), default=0)
287
+ return {
288
+ "tool_calls": agg["calls"], "tool_errors": agg["errors"], "by_tool": dict(agg["by"]),
289
+ "max_identical_run": agg["max"],
290
+ # AgentsView (MIT): a retry loop is 3+ identical calls in a row; a runaway turn is
291
+ # 6+ errors, or 3+ errors while one tool was called 10+ times.
292
+ "retry_flag": agg["max"] >= 3,
293
+ "runaway_flag": agg["errors"] >= 6 or (agg["errors"] >= 3 and top >= 10),
294
+ }