repeat-o-scope 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.
@@ -0,0 +1,262 @@
1
+ """Measures wasted turns: API calls spent on errors, re-reads, go-aheads, expired caches and an overfull context."""
2
+
3
+ import collections
4
+ import logging
5
+ from collections.abc import Iterator
6
+ from dataclasses import dataclass, field
7
+ from datetime import datetime, timedelta
8
+ from itertools import pairwise
9
+ from pathlib import Path
10
+
11
+ from repeat_o_scope import transcripts
12
+ from repeat_o_scope.redaction import redact
13
+
14
+ _LOGGER = logging.getLogger(__name__)
15
+
16
+ KINDS = ('refused_edit', 'reread', 'failed', 'denied', 'bare_yes', 'cache_rebuild', 'long_context')
17
+ NO_EVIDENCE = '(no text)'
18
+ _REFUSED_EDIT = 'has not been read yet'
19
+ _EDITS = frozenset({'Edit', 'Write', 'NotebookEdit'})
20
+ _CONTEXT_WINDOWS = (200_000, 1_000_000)
21
+ _TOKEN_KEYS = ('input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens', 'output_tokens')
22
+ # API price ratios against an input token: the best public proxy for how much of a usage limit a call takes.
23
+ _OUTPUT = 5.0
24
+ _WRITE_5M = 1.25
25
+ _WRITE_1H = 2.0
26
+ # Cache reads got cheaper relative to input with the newer models; matched as a prefix of `message.model`.
27
+ _CACHE_READS = {
28
+ 'claude-fable-5-1': 0.025,
29
+ 'claude-fable-5-2': 0.025,
30
+ 'claude-mythos-5-1': 0.025,
31
+ 'claude-mythos-5-2': 0.025,
32
+ 'claude-opus-5-5': 0.05,
33
+ 'claude-sonnet-5-5': 0.05,
34
+ }
35
+ _CACHE_READ = 0.1
36
+ _TTL_5M = timedelta(minutes=5)
37
+ _TTL_1H = timedelta(hours=1)
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class Tally:
42
+ turns: int
43
+ tokens: int
44
+ weight: float
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class Charge:
49
+ """One wasted call: its kind, what it was about (redacted), and its cost."""
50
+
51
+ kind: str
52
+ evidence: str
53
+ tally: Tally
54
+
55
+
56
+ @dataclass(frozen=True)
57
+ class Measurement:
58
+ days: int
59
+ total: Tally
60
+ waste: dict[str, Tally]
61
+ # Calls charged to a kind with text behind it; expired caches and long contexts have none.
62
+ charges: list[Charge] = field(default_factory=list)
63
+
64
+
65
+ @dataclass(frozen=True)
66
+ class _Call:
67
+ at: datetime | None
68
+ context: tuple
69
+ model: str | None
70
+ usage: dict
71
+
72
+
73
+ def measure(*, days: int, root: Path, since: datetime) -> Measurement:
74
+ """Returns the turns and tokens spent in the window, and those wasted per kind."""
75
+ calls: dict[str, _Call] = {}
76
+ # Call id -> (kind, evidence); the first charge wins.
77
+ charges: dict[str, tuple[str, str]] = {}
78
+ issuer: dict[str, tuple[str, str]] = {}
79
+ seen: dict[tuple, set[tuple]] = collections.defaultdict(set)
80
+ closing: dict[tuple, str] = {}
81
+ go_ahead: dict[tuple, str] = {}
82
+ for e in transcripts.iter_entries(root=root, since=since, subagents=True):
83
+ # Cowork's audit.jsonl uses the Agent SDK's `session_id`.
84
+ context = (e.get('sessionId') or e.get('session_id'), e.get('agentId'))
85
+ if e.get('isCompactSummary'):
86
+ # Compaction drops what was read, so reading it again is needed.
87
+ seen[context].clear()
88
+ # Condition copied from `iter_turn_ends`: a reply counts only after Claude said something in that session.
89
+ if (text := transcripts.typed_text(e)) and context in closing and transcripts.is_go_ahead(text):
90
+ go_ahead[context] = closing[context]
91
+ message = e.get('message') or {}
92
+ call_id, usage = message.get('id'), message.get('usage')
93
+ is_call = e.get('type') == 'assistant' and isinstance(call_id, str) and isinstance(usage, dict)
94
+ if is_call:
95
+ model = message.get('model')
96
+ calls.setdefault(call_id, _Call(
97
+ at=_timestamp(e),
98
+ context=context,
99
+ model=model if isinstance(model, str) else None,
100
+ usage=usage,
101
+ ))
102
+ if line := transcripts.last_line(transcripts.message_text(e)):
103
+ closing[context] = line
104
+ else:
105
+ closing.setdefault(context, '')
106
+ if context in go_ahead:
107
+ charges.setdefault(call_id, ('bare_yes', go_ahead.pop(context)))
108
+ for block in _blocks(message):
109
+ if block.get('type') == 'tool_use' and is_call:
110
+ tool_input = block.get('input')
111
+ issuer[block.get('id')] = (call_id, f'{block.get("name") or "?"}: {transcripts.attempt(tool_input)}')
112
+ if _is_reread(block, seen=seen[context]):
113
+ path = tool_input.get('file_path') or tool_input.get('notebook_path')
114
+ charges.setdefault(call_id, ('reread', path))
115
+ elif block.get('type') == 'tool_result' and block.get('is_error'):
116
+ if (by := issuer.get(block.get('tool_use_id'))) is not None:
117
+ error = transcripts.error_line(block.get('content'))
118
+ charges.setdefault(by[0], (_error_kind(error), f'{by[1]} → {error or NO_EVIDENCE}'))
119
+ waste = {kind: _tally([calls[c] for c, (k, _) in charges.items() if k == kind]) for kind in KINDS}
120
+ rebuilt = _rebuilds(calls, charged=charges.keys())
121
+ waste['cache_rebuild'] = Tally(
122
+ turns=len(rebuilt),
123
+ tokens=sum(tokens for tokens, _ in rebuilt.values()),
124
+ weight=sum(weight for _, weight in rebuilt.values()),
125
+ )
126
+ waste['long_context'] = _long_context(
127
+ [call for c, call in calls.items() if c not in charges and c not in rebuilt],
128
+ windows=_windows(calls.values()),
129
+ )
130
+ total = _tally(list(calls.values()))
131
+ _LOGGER.info('Measured `%s` turns, `%s` wasted.', total.turns, sum(t.turns for t in waste.values()))
132
+ charged = [
133
+ Charge(kind=charges[c][0], evidence=redact(charges[c][1] or NO_EVIDENCE), tally=_tally([call]))
134
+ for c, call in calls.items()
135
+ if c in charges
136
+ ]
137
+ return Measurement(days=days, total=total, waste=waste, charges=charged)
138
+
139
+
140
+ def _blocks(message: dict) -> Iterator[dict]:
141
+ content = message.get('content')
142
+ if isinstance(content, list):
143
+ yield from (b for b in content if isinstance(b, dict))
144
+
145
+
146
+ def _is_reread(block: dict, *, seen: set[tuple]) -> bool:
147
+ """Returns whether a tool call reads a range already read in this context; edits make a file new again."""
148
+ tool_input = block.get('input') if isinstance(block.get('input'), dict) else {}
149
+ path = tool_input.get('file_path') or tool_input.get('notebook_path')
150
+ if not isinstance(path, str):
151
+ return False
152
+ if block.get('name') in _EDITS:
153
+ seen.difference_update({r for r in seen if r[0] == path})
154
+ return False
155
+ if block.get('name') != 'Read':
156
+ return False
157
+ read = (path, tool_input.get('offset'), tool_input.get('limit'))
158
+ if read in seen:
159
+ return True
160
+ seen.add(read)
161
+ return False
162
+
163
+
164
+ def _windows(calls) -> dict[tuple, int]:
165
+ """Returns each context's window: the smallest that fits its largest call, since transcripts don't say."""
166
+ largest = collections.defaultdict(int)
167
+ for call in calls:
168
+ largest[call.context] = max(largest[call.context], _context(call.usage))
169
+ return {c: next((w for w in _CONTEXT_WINDOWS if w >= n), _CONTEXT_WINDOWS[-1]) for c, n in largest.items()}
170
+
171
+
172
+ def _rebuilds(calls: dict[str, _Call], *, charged) -> dict[str, tuple[int, float]]:
173
+ """Returns the tokens and extra weight of each uncharged call that rewrote a cache that expired in a gap."""
174
+ # The extra weight is what writing the previous context again cost above reading it from a warm cache.
175
+ by_context = collections.defaultdict(list)
176
+ for call_id, call in calls.items():
177
+ if call.at is not None:
178
+ by_context[call.context].append((call.at, call_id, call))
179
+ rebuilt = {}
180
+ for timed in by_context.values():
181
+ ttl = _ttl([call for _, _, call in timed])
182
+ for (prev_at, _, prev), (at, call_id, call) in pairwise(sorted(timed, key=lambda t: t[0])):
183
+ written = _count(call.usage, 'cache_creation_input_tokens')
184
+ if at - prev_at > ttl and written and call_id not in charged:
185
+ tokens = min(written, _context(prev.usage))
186
+ rebuilt[call_id] = (tokens, tokens * (_write_weight(call.usage) / written - _read_ratio(call.model)))
187
+ return rebuilt
188
+
189
+
190
+ def _ttl(calls: list[_Call]) -> timedelta:
191
+ """Returns a context's cache lifetime: 1 hour if most of its cache writes were 1-hour ones."""
192
+ written = sum(_count(c.usage, 'cache_creation_input_tokens') for c in calls)
193
+ one_hour = sum(_count(_split(c.usage), 'ephemeral_1h_input_tokens') for c in calls)
194
+ return _TTL_1H if one_hour * 2 > written else _TTL_5M
195
+
196
+
197
+ def _timestamp(e: dict) -> datetime | None:
198
+ try:
199
+ return datetime.fromisoformat(e['timestamp'])
200
+ except (KeyError, TypeError, ValueError):
201
+ return None
202
+
203
+
204
+ def _long_context(uncharged: list[_Call], *, windows: dict[tuple, int]) -> Tally:
205
+ """Returns the tally of the context each call carried above half its window."""
206
+ turns, tokens, weight = 0, 0, 0.0
207
+ for call in uncharged:
208
+ if (excess := _context(call.usage) - windows[call.context] // 2) > 0:
209
+ turns, tokens = turns + 1, tokens + excess
210
+ weight += _weight(call) * excess / _context(call.usage)
211
+ return Tally(turns=turns, tokens=tokens, weight=weight)
212
+
213
+
214
+ def _context(usage: dict) -> int:
215
+ return sum(_count(usage, key) for key in ('input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens'))
216
+
217
+
218
+ def _error_kind(error: str) -> str:
219
+ if transcripts.is_denial(error):
220
+ return 'denied'
221
+ return 'refused_edit' if _REFUSED_EDIT in error else 'failed'
222
+
223
+
224
+ def _tally(calls: list[_Call]) -> Tally:
225
+ return Tally(
226
+ turns=len(calls),
227
+ tokens=sum(_count(c.usage, key) for c in calls for key in _TOKEN_KEYS),
228
+ weight=sum(map(_weight, calls)),
229
+ )
230
+
231
+
232
+ def _weight(call: _Call) -> float:
233
+ """Returns how much of a usage limit a call takes, in input-token equivalents."""
234
+ usage = call.usage
235
+ return (
236
+ _count(usage, 'input_tokens')
237
+ + _write_weight(usage)
238
+ + _count(usage, 'cache_read_input_tokens') * _read_ratio(call.model)
239
+ + _count(usage, 'output_tokens') * _OUTPUT
240
+ )
241
+
242
+
243
+ def _write_weight(usage: dict) -> float:
244
+ """Returns the weight of a call's cache writes; a write without the TTL split counts as 5-minute."""
245
+ written = _count(usage, 'cache_creation_input_tokens')
246
+ one_hour = min(_count(_split(usage), 'ephemeral_1h_input_tokens'), written)
247
+ return one_hour * _WRITE_1H + (written - one_hour) * _WRITE_5M
248
+
249
+
250
+ def _split(usage: dict) -> dict:
251
+ """Returns the cache writes split by TTL, which older transcripts don't have."""
252
+ split = usage.get('cache_creation')
253
+ return split if isinstance(split, dict) else {}
254
+
255
+
256
+ def _read_ratio(model: str | None) -> float:
257
+ return next((r for prefix, r in _CACHE_READS.items() if model and model.startswith(prefix)), _CACHE_READ)
258
+
259
+
260
+ def _count(usage: dict, key: str) -> int:
261
+ value = usage.get(key)
262
+ return value if isinstance(value, int) else 0
@@ -0,0 +1,233 @@
1
+ """Claude Code Stop hook: appends one work-log entry per stretch of work per session.
2
+
3
+ Port of `worklog.ps1`. Each line is a JSON-LD node keyed by @id (session_id + seq) and
4
+ prefixed s<index>.<seq>: index is a global per-session counter, seq increments after a
5
+ gap of `_GAP` without a Stop. Within a stretch the same @id is re-appended with the
6
+ growing totals, so a reader keeps the LAST line per @id. The log is always current, even
7
+ for sessions that never end.
8
+
9
+ Output: <log dir>/YYYY-MM-DD.jsonl (date of the stretch's first turn; default: the user data dir)
10
+ State: <state dir>/<session_id>.json (transcript offset, seq, stretch so far)
11
+ Input: <state dir>/<session_id>.rate-limits.json (the status line's latest `rate_limits`)
12
+ """
13
+
14
+ import json
15
+ import logging
16
+ import os
17
+ import re
18
+ import subprocess
19
+ import sys
20
+ import time
21
+ from datetime import datetime, timedelta
22
+ from pathlib import Path
23
+
24
+ import platformdirs
25
+
26
+ from repeat_o_scope.redaction import redact
27
+
28
+ _LOGGER = logging.getLogger(__name__)
29
+
30
+ _GAP = timedelta(minutes=15)
31
+ _MAX_PROMPTS = 10
32
+ _MAX_PROMPT_CHARS = 200
33
+ _GIT_TIMEOUT_SECONDS = 5
34
+ _EDIT_TOOLS = frozenset({'Edit', 'Write', 'MultiEdit', 'NotebookEdit'})
35
+ # Written by statusline/statusline.ps1 next to the session's state file.
36
+ _RATE_LIMITS_SUFFIX = '.rate-limits.json'
37
+ _RATE_LIMIT_WINDOWS = ('five_hour', 'seven_day')
38
+ # Tool results, slash-command plumbing and injected reminders.
39
+ _PLUMBING = re.compile(r'^\s*<(command-|local-command|system-reminder)', re.IGNORECASE)
40
+ _CONTEXT = {
41
+ '@vocab': 'urn:repeat-o-scope:worklog#',
42
+ 'started': {'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
43
+ 'last_stop': {'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
44
+ 'repo': {'@type': '@id'},
45
+ 'files': {'@container': '@set'},
46
+ 'prompts': {'@container': '@list'},
47
+ }
48
+
49
+
50
+ def record_stop(
51
+ *,
52
+ hook: dict,
53
+ log_dir: Path,
54
+ now: datetime,
55
+ state_dir: Path,
56
+ ) -> None:
57
+ """Appends the current stretch of the hook's session to the day's log."""
58
+ sid = hook.get('session_id')
59
+ transcript = hook.get('transcript_path')
60
+ if not sid or not transcript or not Path(transcript).exists():
61
+ return
62
+
63
+ log_dir.mkdir(parents=True, exist_ok=True)
64
+ state_dir.mkdir(parents=True, exist_ok=True)
65
+ state_path = state_dir / f'{sid}.json'
66
+ state = json.loads(state_path.read_text(encoding='utf-8-sig')) if state_path.exists() else None
67
+
68
+ if not state or now - datetime.fromisoformat(state['last_stop']) >= _GAP:
69
+ seq = state['seq'] + 1 if state else 1
70
+ started = now.isoformat()
71
+ prompts, files, turns, tools = [], [], 0, 0
72
+ peak = {}
73
+ else:
74
+ seq = state['seq']
75
+ started = state['started']
76
+ prompts, files = list(state['prompts'] or []), list(state['files'] or [])
77
+ turns, tools = state['turns'], state['tool_uses']
78
+ peak = dict(state.get('rate_limit_peak') or {})
79
+ offset = state['offset'] if state else 0
80
+ branch = state.get('branch') if state else None
81
+
82
+ line_no = 0
83
+ with open(transcript, encoding='utf-8') as f:
84
+ for line in f:
85
+ line_no += 1
86
+ line = line.rstrip('\r\n')
87
+ if line_no <= offset or not line:
88
+ continue
89
+ try:
90
+ e = json.loads(line)
91
+ except json.JSONDecodeError:
92
+ continue
93
+ if not isinstance(e, dict):
94
+ continue
95
+ if e.get('gitBranch'):
96
+ branch = e['gitBranch']
97
+ content = (e.get('message') or {}).get('content')
98
+ if e.get('type') == 'user' and not e.get('isMeta'):
99
+ text = _prompt_text(content)
100
+ if text and not _PLUMBING.match(text):
101
+ prompts.append(_clean(text))
102
+ turns += 1
103
+ elif e.get('type') == 'assistant' and isinstance(content, list):
104
+ for block in content:
105
+ if block.get('type') != 'tool_use':
106
+ continue
107
+ tools += 1
108
+ # TODO: NotebookEdit takes `notebook_path`, so notebooks never show up. Copied from worklog.ps1.
109
+ path = block.get('name') in _EDIT_TOOLS and block['input'].get('file_path')
110
+ if path and path not in files:
111
+ files.append(path)
112
+
113
+ cwd = hook.get('cwd')
114
+ repo = None
115
+ if cwd and Path(cwd).exists():
116
+ repo = _git(cwd, 'remote', 'get-url', 'origin')
117
+ branch = branch or _git(cwd, 'branch', '--show-current')
118
+
119
+ index = state.get('index') if state else None
120
+ index = index or _next_index(state_dir)
121
+
122
+ # Transcripts don't record rate-limit state, so the status line leaves its latest copy here.
123
+ # A window at 100% means the turns went to extra usage.
124
+ rate_limits = _read_rate_limits(state_dir / f'{sid}{_RATE_LIMITS_SUFFIX}')
125
+ for window in _RATE_LIMIT_WINDOWS:
126
+ used = (rate_limits or {}).get(window, {}).get('used_percentage')
127
+ if isinstance(used, (int, float)):
128
+ peak[window] = max(peak.get(window, 0), used)
129
+
130
+ entry = {
131
+ '@context': _CONTEXT,
132
+ '@id': f'urn:claude-code:session:{sid}#{seq}',
133
+ '@type': 'WorkStretch',
134
+ 'prefix': f's{index:04d}.{seq}',
135
+ 'index': index,
136
+ 'session_id': sid,
137
+ 'seq': seq,
138
+ 'started': started,
139
+ 'last_stop': now.isoformat(),
140
+ 'cwd': cwd,
141
+ 'repo': repo,
142
+ 'branch': branch,
143
+ 'turns': turns,
144
+ 'tool_uses': tools,
145
+ 'files': files,
146
+ 'prompts': prompts[-_MAX_PROMPTS:],
147
+ 'transcript': transcript,
148
+ 'rate_limits': rate_limits,
149
+ 'rate_limit_peak': peak or None,
150
+ }
151
+ day = datetime.fromisoformat(started).strftime('%Y-%m-%d')
152
+ _append(log_dir / f'{day}.jsonl', json.dumps(entry, ensure_ascii=False, separators=(',', ':')) + '\n')
153
+
154
+ state_path.write_text(
155
+ json.dumps({**entry, 'prompts': prompts, 'offset': line_no}, ensure_ascii=False, indent=2),
156
+ encoding='utf-8',
157
+ )
158
+
159
+
160
+ def _prompt_text(content) -> str:
161
+ """Returns the text of a user message; empty for tool results."""
162
+ if isinstance(content, str):
163
+ return content
164
+ if not isinstance(content, list):
165
+ return ''
166
+ return ' '.join(b['text'] for b in content if b.get('type') == 'text')
167
+
168
+
169
+ def _clean(text: str) -> str:
170
+ """Returns the prompt on one line, redacted and cut to `_MAX_PROMPT_CHARS`."""
171
+ # Credentials pasted into a prompt must not reach the log (it may live in a synced folder).
172
+ text = redact(re.sub(r'\s+', ' ', text).strip())
173
+ return text[:_MAX_PROMPT_CHARS] + '...' if len(text) > _MAX_PROMPT_CHARS else text
174
+
175
+
176
+ def _read_rate_limits(path: Path) -> dict | None:
177
+ """Returns the status line's last `rate_limits`, or None when absent or half-written."""
178
+ try:
179
+ data = json.loads(path.read_text(encoding='utf-8-sig'))
180
+ except (OSError, ValueError):
181
+ return None
182
+ if not isinstance(data, dict):
183
+ return None
184
+ # Keep only well-formed windows, so a stray value never breaks the peak.
185
+ return {k: v for k, v in data.items() if isinstance(v, dict)} or None
186
+
187
+
188
+ def _git(cwd: str, *args: str) -> str | None:
189
+ """Returns git's output in `cwd`, or None when git fails or prints nothing."""
190
+ try:
191
+ out = subprocess.run(
192
+ ['git', '-C', cwd, *args],
193
+ capture_output=True,
194
+ text=True,
195
+ timeout=_GIT_TIMEOUT_SECONDS,
196
+ )
197
+ except (OSError, subprocess.TimeoutExpired):
198
+ return None
199
+ return (out.returncode == 0 and out.stdout.strip()) or None
200
+
201
+
202
+ def _next_index(state_dir: Path) -> int:
203
+ """Returns the next global session index: 1, 2, ..."""
204
+ counter = state_dir / '_counter'
205
+ n = int(counter.read_text(encoding='utf-8-sig')) + 1 if counter.exists() else 1
206
+ counter.write_text(f'{n}\n', encoding='utf-8')
207
+ return n
208
+
209
+
210
+ def _append(path: Path, text: str) -> None:
211
+ """Appends `text`, retrying briefly because several sessions can stop at once."""
212
+ for _ in range(5):
213
+ try:
214
+ with path.open('a', encoding='utf-8') as f:
215
+ f.write(text)
216
+ return
217
+ except OSError:
218
+ time.sleep(0.1)
219
+
220
+
221
+ def main() -> None:
222
+ try:
223
+ # Not Documents: Windows ransomware protection (Controlled Folder Access) blocks python and pwsh there.
224
+ default_log = platformdirs.user_data_path('repeat-o-scope', appauthor=False) / 'worklog'
225
+ record_stop(
226
+ hook=json.load(sys.stdin),
227
+ log_dir=Path(os.environ.get('REPEAT_O_SCOPE_LOG_DIR') or default_log),
228
+ now=datetime.now().astimezone(),
229
+ state_dir=Path.home() / '.claude' / 'hooks' / 'worklog-state',
230
+ )
231
+ except Exception:
232
+ # Never break Claude Code over a log line.
233
+ _LOGGER.exception('Worklog hook failed.')