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.
- agent_usage_tracker/__init__.py +8 -0
- agent_usage_tracker/backup.py +225 -0
- agent_usage_tracker/cli.py +479 -0
- agent_usage_tracker/collectors/__init__.py +115 -0
- agent_usage_tracker/collectors/_util.py +310 -0
- agent_usage_tracker/collectors/activity_common.py +294 -0
- agent_usage_tracker/collectors/activitywatch.py +394 -0
- agent_usage_tracker/collectors/claude_code.py +484 -0
- agent_usage_tracker/collectors/claude_code_activity.py +317 -0
- agent_usage_tracker/collectors/codex.py +612 -0
- agent_usage_tracker/collectors/commits.py +154 -0
- agent_usage_tracker/collectors/cursor.py +193 -0
- agent_usage_tracker/collectors/cursor_api.py +247 -0
- agent_usage_tracker/collectors/cursor_cli.py +592 -0
- agent_usage_tracker/collectors/cursor_sdk.py +95 -0
- agent_usage_tracker/collectors/generic_sdk.py +100 -0
- agent_usage_tracker/collectors/pi.py +397 -0
- agent_usage_tracker/collectors/session_digest.py +379 -0
- agent_usage_tracker/collectors/t3.py +490 -0
- agent_usage_tracker/config.py +392 -0
- agent_usage_tracker/coverage.py +615 -0
- agent_usage_tracker/coverage_catalog.json +588 -0
- agent_usage_tracker/cursor_run.py +62 -0
- agent_usage_tracker/diagnostics.py +74 -0
- agent_usage_tracker/episode_store.py +78 -0
- agent_usage_tracker/event.py +132 -0
- agent_usage_tracker/git_day_cache.py +128 -0
- agent_usage_tracker/git_days.py +499 -0
- agent_usage_tracker/git_safe.py +58 -0
- agent_usage_tracker/harness_inventory.py +208 -0
- agent_usage_tracker/history_steers.py +88 -0
- agent_usage_tracker/improve/__init__.py +1 -0
- agent_usage_tracker/improve/case_view.py +112 -0
- agent_usage_tracker/improve/cli.py +138 -0
- agent_usage_tracker/improve/desktop.py +347 -0
- agent_usage_tracker/improve/evidence.py +322 -0
- agent_usage_tracker/improve/judge.py +671 -0
- agent_usage_tracker/improve/proposals.py +72 -0
- agent_usage_tracker/improve/rubric.py +360 -0
- agent_usage_tracker/improve/rubrics/avoidable_recovery.md +20 -0
- agent_usage_tracker/improve/rubrics/code_quality.md +22 -0
- agent_usage_tracker/improve/rubrics/completion_supported.md +20 -0
- agent_usage_tracker/improve/rubrics/redundant_tests.md +21 -0
- agent_usage_tracker/improve/rubrics/verbosity.md +21 -0
- agent_usage_tracker/improve/runtime.py +117 -0
- agent_usage_tracker/improve/schedule.py +291 -0
- agent_usage_tracker/improve/search_check.py +563 -0
- agent_usage_tracker/improve/store.py +244 -0
- agent_usage_tracker/improve/studies.py +285 -0
- agent_usage_tracker/improve/study_cli.py +46 -0
- agent_usage_tracker/improve/study_decision.py +121 -0
- agent_usage_tracker/improve/study_followup.py +174 -0
- agent_usage_tracker/improve/t3.py +269 -0
- agent_usage_tracker/improve/trial.py +318 -0
- agent_usage_tracker/improve/validation.py +148 -0
- agent_usage_tracker/inspector.py +350 -0
- agent_usage_tracker/label/__init__.py +22 -0
- agent_usage_tracker/label/backends.py +742 -0
- agent_usage_tracker/label/bakeoff.py +661 -0
- agent_usage_tracker/label/baseline.py +173 -0
- agent_usage_tracker/label/clef.py +258 -0
- agent_usage_tracker/label/context.py +382 -0
- agent_usage_tracker/label/core.py +355 -0
- agent_usage_tracker/label/covered_run.py +92 -0
- agent_usage_tracker/label/evalset.py +154 -0
- agent_usage_tracker/label/gold.py +209 -0
- agent_usage_tracker/label/local.py +326 -0
- agent_usage_tracker/label/local_parallel.py +232 -0
- agent_usage_tracker/label/merge.py +57 -0
- agent_usage_tracker/label/outcome_coverage.py +57 -0
- agent_usage_tracker/label/replay.py +194 -0
- agent_usage_tracker/label/run.py +339 -0
- agent_usage_tracker/label/tasks.py +579 -0
- agent_usage_tracker/label/teach.py +145 -0
- agent_usage_tracker/local_page.py +128 -0
- agent_usage_tracker/manual_time.py +69 -0
- agent_usage_tracker/net.py +23 -0
- agent_usage_tracker/observation_cli.py +65 -0
- agent_usage_tracker/observation_report.py +116 -0
- agent_usage_tracker/observation_server.py +110 -0
- agent_usage_tracker/observations.py +365 -0
- agent_usage_tracker/outcome_git.py +383 -0
- agent_usage_tracker/outcomes.py +464 -0
- agent_usage_tracker/pricing.py +248 -0
- agent_usage_tracker/push.py +530 -0
- agent_usage_tracker/redact.py +45 -0
- agent_usage_tracker/repo_keys.py +165 -0
- agent_usage_tracker/review.py +252 -0
- agent_usage_tracker/scan.py +472 -0
- agent_usage_tracker/scheduled.py +164 -0
- agent_usage_tracker/sdk.py +79 -0
- agent_usage_tracker/sink.py +82 -0
- agent_usage_tracker/sink_stack/README.md +71 -0
- agent_usage_tracker/sink_stack/apply.sh +63 -0
- agent_usage_tracker/sink_stack/compose.yaml +94 -0
- agent_usage_tracker/sink_stack/env.example +20 -0
- agent_usage_tracker/sink_stack/grafana/dashboards/agents-effort.json +634 -0
- agent_usage_tracker/sink_stack/grafana/dashboards/agents-usage.json +1279 -0
- agent_usage_tracker/sink_stack/grafana/provisioning/dashboards/aut.yaml +9 -0
- agent_usage_tracker/sink_stack/grafana/provisioning/datasources/agents.yaml +16 -0
- agent_usage_tracker/sink_stack/sql/01_schema.sql +1186 -0
- agent_usage_tracker/sink_stack/sql/02_price.sql +60 -0
- agent_usage_tracker/sink_stack/sql/03_effort.sql +1180 -0
- agent_usage_tracker/sink_stack/sql/04_grants.sql +149 -0
- agent_usage_tracker/sink_stack/sql/refresh.sql +66 -0
- agent_usage_tracker/sources.py +180 -0
- agent_usage_tracker/state.py +191 -0
- agent_usage_tracker/telemetry.py +165 -0
- agent_usage_tracker-0.1.0.dist-info/METADATA +366 -0
- agent_usage_tracker-0.1.0.dist-info/RECORD +113 -0
- agent_usage_tracker-0.1.0.dist-info/WHEEL +4 -0
- agent_usage_tracker-0.1.0.dist-info/entry_points.txt +3 -0
- 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
|
+
}
|