ai-ledger 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.
ai_ledger/__init__.py ADDED
File without changes
ai_ledger/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .app import main
2
+
3
+ main()
ai_ledger/app.py ADDED
@@ -0,0 +1,311 @@
1
+ """Local app: owns the transcript store, keeps it current, serves the Activity, Cost, Errors, Limits, Insights and Live pages.
2
+
3
+ Usage:
4
+ ai-ledger serve on http://127.0.0.1:8765 (ingests at start and every 60 seconds, every second while Live is open)
5
+ ai-ledger ingest ingest new transcript lines and /insights usage data once, then exit
6
+ ai-ledger rebuild regenerate the derived tables from the stored raw lines
7
+ """
8
+ import argparse
9
+ import collections
10
+ import importlib.metadata
11
+ import json
12
+ import os
13
+ import sys
14
+ import threading
15
+ import time
16
+ from datetime import datetime, timezone
17
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
18
+ from urllib.parse import parse_qs, urlsplit
19
+
20
+ from . import insights, limits, live, metrics, store
21
+
22
+ HOST, PORT = "127.0.0.1", 8765 # PORT is the default; --port changes it
23
+ INTERVAL = 60
24
+ LIVE_INTERVAL = 1 # transcript ingest while a Live page is connected; usage data and limits stay on INTERVAL
25
+ KEEPALIVE = 15 # seconds between SSE comments, so a closed Live page is noticed
26
+ WEB = os.path.join(store.HERE, "web") # the committed frontend build (npm run build in web/), shipped in the package
27
+ PAGES = ("/usage", "/cost", "/errors", "/limits", "/insights", "/live") # one app; it picks the page from the path
28
+ ASSET_TYPES = {".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml",
29
+ ".png": "image/png", ".woff2": "font/woff2", ".json": "application/json; charset=utf-8"}
30
+
31
+
32
+ class App:
33
+ def __init__(self, con, roots, pollers=None):
34
+ self.con, self.roots = con, roots
35
+ self.pollers = limits.pollers() if pollers is None else pollers
36
+ self.lock = threading.Lock()
37
+ self.wake = threading.Event()
38
+ self.stopping = threading.Event()
39
+ self.state = dict(ingesting=False, last_ingest=None, last_stats=None, error=None)
40
+ # Live pages: how many are connected, and the sessions each ingest changed, numbered so each page sends a
41
+ # notice for every change since its last one.
42
+ self.watchers = 0
43
+ self.changed = threading.Condition()
44
+ self.generation = 0
45
+ self.changes = collections.deque(maxlen=64)
46
+
47
+ def ingest(self, usage=True):
48
+ """Ingest transcripts, and usage data unless usage is False (the fast pass while Live is open)."""
49
+ with self.lock:
50
+ self.state["ingesting"] = True
51
+ try:
52
+ stats = store.ingest(self.con, self.roots, log=None, usage=usage)
53
+ sessions = stats.pop("sessions")
54
+ self.state.update(last_ingest=datetime.now(timezone.utc).isoformat(timespec="seconds"),
55
+ last_stats=stats, error=None)
56
+ if sessions:
57
+ self.publish(sessions)
58
+ if usage and (stats["files"] or stats.get("usage_files") or stats.get("usage_skipped")):
59
+ print(f"ingest: {stats['files']} files, {stats['inserted']} new lines, {stats.get('usage_files', 0)} usage-data files "
60
+ f"({stats.get('usage_skipped', 0)} skipped), {stats['seconds']}s", flush=True)
61
+ except Exception as e: # keep serving; the next run retries
62
+ self.state["error"] = f"{type(e).__name__}: {e}"
63
+ print("ingest failed:", self.state["error"], file=sys.stderr, flush=True)
64
+ finally:
65
+ self.state["ingesting"] = False
66
+
67
+ def poll(self):
68
+ """Poll each provider's plan limits that is due. A poller never raises, so ingest goes on whatever the endpoint does."""
69
+ for p in self.pollers:
70
+ if p.due():
71
+ p.run(self.con, self.lock)
72
+
73
+ def loop(self):
74
+ """Ingest everything and poll limits every INTERVAL; in between, ingest transcripts every LIVE_INTERVAL while a
75
+ Live page is connected."""
76
+ due = 0
77
+ while not self.stopping.is_set():
78
+ if time.monotonic() >= due:
79
+ self.ingest()
80
+ self.poll()
81
+ due = time.monotonic() + INTERVAL
82
+ elif self.watchers:
83
+ self.ingest(usage=False)
84
+ self.wake.wait(LIVE_INTERVAL if self.watchers else max(0, due - time.monotonic()))
85
+ self.wake.clear()
86
+
87
+ def stop(self, thread):
88
+ """End the ingest loop so nothing holds the connection at exit (DuckDB's bindings warn about leaks otherwise)."""
89
+ self.stopping.set()
90
+ self.wake.set()
91
+ with self.changed:
92
+ self.changed.notify_all() # Live streams return
93
+ thread.join()
94
+
95
+ def publish(self, sessions):
96
+ with self.changed:
97
+ self.generation += 1
98
+ self.changes.append((self.generation, frozenset(sessions)))
99
+ self.changed.notify_all()
100
+
101
+ def changes_since(self, generation, timeout):
102
+ """(newest generation, sessions changed after generation), waiting up to timeout for a change. None for the
103
+ sessions when the change log no longer reaches back that far: the page then refetches everything."""
104
+ with self.changed:
105
+ if self.generation == generation and not self.stopping.is_set():
106
+ self.changed.wait(timeout)
107
+ newer = [s for g, s in self.changes if g > generation]
108
+ if self.generation - generation > len(newer):
109
+ return self.generation, None
110
+ return self.generation, frozenset().union(*newer)
111
+
112
+ def watch(self, delta):
113
+ """Count a Live page in (+1) or out (-1); the first one starts the fast pass at once."""
114
+ with self.changed:
115
+ self.watchers += delta
116
+ first = delta > 0 and self.watchers == 1
117
+ if first:
118
+ self.wake.set()
119
+
120
+ def status(self):
121
+ cur = self.con.cursor()
122
+ counts = {t: cur.execute(f"SELECT count(*) FROM {t}").fetchone()[0] for t in ("raw_lines", "files", "sessions", "requests", "tool_calls")}
123
+ return dict(self.state, counts=counts, interval=INTERVAL, limits={p.name: dict(p.state) for p in self.pollers})
124
+
125
+
126
+ def asset(path):
127
+ """The build file at /assets/<name>, or None when the name leaves the build's assets folder or has no known type."""
128
+ base = os.path.realpath(os.path.join(WEB, "assets"))
129
+ full = os.path.realpath(os.path.join(base, path[len("/assets/"):]))
130
+ ext = os.path.splitext(full)[1]
131
+ return (full, ASSET_TYPES[ext]) if os.path.dirname(full) == base and ext in ASSET_TYPES and os.path.isfile(full) else None
132
+
133
+
134
+ def handler(app, port=PORT):
135
+ class Handler(BaseHTTPRequestHandler):
136
+ def send(self, code, body, ctype="application/json; charset=utf-8", headers=(), cache="no-store"):
137
+ data = body if isinstance(body, bytes) else body.encode()
138
+ self.send_response(code)
139
+ self.send_header("Content-Type", ctype)
140
+ self.send_header("Content-Length", str(len(data)))
141
+ self.send_header("Cache-Control", cache)
142
+ for k, v in headers:
143
+ self.send_header(k, v)
144
+ self.end_headers()
145
+ self.wfile.write(data)
146
+
147
+ def json(self, obj):
148
+ self.send(200, json.dumps(obj, separators=(",", ":"), default=str))
149
+
150
+ def live_events(self):
151
+ """Server-Sent Events for a Live page: a changed notice naming the sessions that gained lines (never their
152
+ content), or a keep-alive comment every KEEPALIVE seconds. Runs until the page goes or the app stops."""
153
+ self.send_response(200)
154
+ for k, v in (("Content-Type", "text/event-stream"), ("Cache-Control", "no-store"), ("X-Accel-Buffering", "no")):
155
+ self.send_header(k, v)
156
+ self.end_headers()
157
+ app.watch(1)
158
+ try:
159
+ generation = app.generation
160
+ self.wfile.write(b"retry: 2000\n\n")
161
+ self.wfile.flush()
162
+ while not app.stopping.is_set():
163
+ generation, sessions = app.changes_since(generation, KEEPALIVE)
164
+ if sessions is None:
165
+ msg = 'event: changed\ndata: {"sessions":null}\n\n'
166
+ elif sessions:
167
+ msg = f"event: changed\ndata: {json.dumps(dict(sessions=sorted(sessions)))}\n\n"
168
+ else:
169
+ msg = ": keep-alive\n\n"
170
+ self.wfile.write(msg.encode())
171
+ self.wfile.flush()
172
+ except (BrokenPipeError, ConnectionResetError):
173
+ pass
174
+ finally:
175
+ app.watch(-1)
176
+
177
+ def checked_host(self):
178
+ """Serve only 127.0.0.1; send localhost there (fix markers live in that origin); refuse other hosts."""
179
+ host = (self.headers.get("Host") or "").lower()
180
+ if host == f"localhost:{port}":
181
+ self.send(301, "", headers=[("Location", f"http://{HOST}:{port}{self.path}")])
182
+ return False
183
+ if host != f"{HOST}:{port}":
184
+ self.send(403, "forbidden host\n", "text/plain")
185
+ return False
186
+ return True
187
+
188
+ def do_GET(self):
189
+ if not self.checked_host():
190
+ return
191
+ url = urlsplit(self.path)
192
+ q = {k: v[0] for k, v in parse_qs(url.query).items()}
193
+ try:
194
+ if url.path == "/":
195
+ self.send(302, "", headers=[("Location", "/usage")])
196
+ elif url.path in PAGES:
197
+ try:
198
+ with open(os.path.join(WEB, "index.html"), "rb") as fh:
199
+ self.send(200, fh.read(), "text/html; charset=utf-8")
200
+ except FileNotFoundError:
201
+ self.send(503, "frontend build missing: run npm install && npm run build in web/\n", "text/plain")
202
+ elif url.path.startswith("/assets/"):
203
+ found = asset(url.path)
204
+ if found is None:
205
+ self.send(404, "not found\n", "text/plain")
206
+ else: # names carry a content hash, so a file never changes
207
+ with open(found[0], "rb") as fh:
208
+ self.send(200, fh.read(), found[1], cache="public, max-age=31536000, immutable")
209
+ elif url.path == "/api/live/events":
210
+ self.live_events()
211
+ elif url.path == "/api/live":
212
+ self.json(live.sessions(app.con.cursor(), q.get("project", ""), q.get("source", ""), automated=q.get("automated") == "1",
213
+ text=q.get("text") == "1"))
214
+ elif url.path == "/api/live/session":
215
+ detail = live.session(app.con.cursor(), q.get("id", ""), q.get("after", ""), text=q.get("text") == "1")
216
+ self.send(404, json.dumps(dict(error="session not found"))) if detail is None else self.json(detail)
217
+ elif url.path == "/api/status":
218
+ self.json(app.status())
219
+ elif url.path == "/api/errors":
220
+ self.json(metrics.errors_payload(app.con.cursor(), app.state["last_ingest"]))
221
+ elif url.path == "/api/error":
222
+ detail = metrics.error_detail(app.con.cursor(), q.get("id", ""))
223
+ self.send(404, json.dumps(dict(error="error not found"))) if detail is None else self.json(detail)
224
+ elif url.path == "/api/session":
225
+ detail = metrics.session(app.con.cursor(), q.get("id", ""))
226
+ self.send(404, json.dumps(dict(error="session not found"))) if detail is None else self.json(detail)
227
+ elif url.path == "/api/prompt": # the session's whole first prompt; /api/session caps it
228
+ text = metrics.first_prompt(app.con.cursor(), q.get("session", ""), cap=None)
229
+ self.send(404, json.dumps(dict(error="prompt not found"))) if text is None else self.json(dict(text=text))
230
+ elif url.path == "/api/sessions":
231
+ self.json(metrics.session_list(app.con.cursor(), q.get("project", ""), int(q.get("range") or 0), q.get("q", ""),
232
+ q.get("near") == "1", int(q.get("offset") or 0), day=q.get("day", ""),
233
+ automated=q.get("automated") == "1", source=q.get("source", "")))
234
+ elif url.path == "/api/palette":
235
+ self.json(metrics.palette(app.con.cursor(), q.get("project", ""), int(q.get("range") or 0),
236
+ automated=q.get("automated") == "1", source=q.get("source", "")))
237
+ elif url.path == "/api/limits":
238
+ self.json(limits.payload(app.con.cursor(), int(q.get("range") or 0), q.get("source", ""), q.get("project", ""),
239
+ polls={p.name: dict(p.state) for p in app.pollers}))
240
+ elif url.path == "/api/insights":
241
+ self.json(insights.payload(app.con.cursor(), q.get("project", ""), int(q.get("range") or 0), q.get("source", ""),
242
+ automated=q.get("automated") == "1", usage_dir=app.roots.get("insights")))
243
+ elif url.path == "/api/tool":
244
+ self.json(metrics.tool_detail(app.con.cursor(), q.get("kind", ""), q.get("name", ""), q.get("project", ""),
245
+ int(q.get("range") or 0), automated=q.get("automated") == "1", source=q.get("source", "")))
246
+ elif url.path == "/api/usage":
247
+ self.json(metrics.usage(app.con.cursor(), q.get("project", ""), int(q.get("range") or 0), q.get("session", ""),
248
+ automated=q.get("automated") == "1", source=q.get("source", "")))
249
+ else:
250
+ self.send(404, "not found\n", "text/plain")
251
+ except ValueError as e:
252
+ self.send(400, json.dumps(dict(error=str(e))))
253
+
254
+ def do_POST(self):
255
+ if not self.checked_host():
256
+ return
257
+ if urlsplit(self.path).path != "/api/refresh":
258
+ return self.send(404, "not found\n", "text/plain")
259
+ app.ingest()
260
+ self.json(app.status())
261
+
262
+ def log_message(self, fmt, *args):
263
+ pass
264
+
265
+ return Handler
266
+
267
+
268
+ def serve(con, roots, port=PORT):
269
+ app = App(con, roots)
270
+ try:
271
+ httpd = ThreadingHTTPServer((HOST, port), handler(app, port))
272
+ except OSError as e:
273
+ sys.exit(f"cannot listen on {HOST}:{port}: {e}; pass --port to use another port")
274
+ loop = threading.Thread(target=app.loop, daemon=True)
275
+ loop.start()
276
+ print(f"serving http://{HOST}:{port}/ (ingest every {INTERVAL}s)", flush=True)
277
+ try:
278
+ httpd.serve_forever()
279
+ except KeyboardInterrupt:
280
+ pass
281
+ finally:
282
+ httpd.server_close()
283
+ app.stop(loop)
284
+
285
+
286
+ def main(argv=None):
287
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
288
+ ap.add_argument("command", nargs="?", choices=["serve", "ingest", "rebuild"], default="serve")
289
+ ap.add_argument("--projects", default=store.DEFAULT_ROOT, help="Claude Code transcript root")
290
+ ap.add_argument("--codex", default=store.DEFAULT_CODEX, help="Codex home")
291
+ ap.add_argument("--usage-data", default=store.DEFAULT_USAGE_DATA, help="Claude Code /insights usage-data directory")
292
+ ap.add_argument("--db", help=f"database file (default {store.DEFAULT_DB})")
293
+ ap.add_argument("--port", type=int, default=PORT, help=f"port to serve on at {HOST} (default {PORT})")
294
+ ap.add_argument("--version", action="version", version=f"ai-ledger {importlib.metadata.version('ai-ledger')}")
295
+ a = ap.parse_args(argv)
296
+ roots = dict(claude=a.projects, codex=a.codex, insights=a.usage_data)
297
+ try:
298
+ con = store.open_store(a.db)
299
+ except (store.StoreBusy, store.StoreNotMoved) as e:
300
+ print(e, file=sys.stderr)
301
+ sys.exit(1)
302
+ if a.command == "serve":
303
+ serve(con, roots, a.port)
304
+ elif a.command == "ingest":
305
+ t = time.time()
306
+ print(store.ingest(con, roots, log=print))
307
+ print(f"done in {time.time() - t:.1f}s")
308
+ else:
309
+ print(store.rebuild(con))
310
+ con.close()
311
+
@@ -0,0 +1,200 @@
1
+ """Error categories for failed tool calls, and the helpers that read tool inputs and results.
2
+
3
+ Ingest uses this to categorize errors. Add a rule to RULES when a new error pattern shows up in "Other".
4
+ """
5
+ import json
6
+ import os
7
+ import re
8
+ from urllib.parse import urlsplit
9
+
10
+ # Commands that run tests, builds or linters. A call matching this is a test run; it passed when it did not fail.
11
+ TEST_CMD = re.compile(r"\b(npm|pnpm|yarn|bun|npx|vitest|jest|pytest|cargo|tsc|phpunit|pest|go test|go build|make|eslint|ruff|mypy|artisan test|composer)\b")
12
+ # A shell command that runs `git commit`, allowing global options such as `-C <dir>`.
13
+ GIT_COMMIT = re.compile(r"\bgit\b(\s+-\S+(\s+\S+)?)*\s+commit\b")
14
+ # Tool names that run a shell command, per source: Claude Code's and Codex's. TEST_CMD and GIT_COMMIT apply to these.
15
+ SHELL_TOOLS = {"Bash", "exec_command"}
16
+
17
+ # First matching rule wins. Each rule: id, label, test(err, tool, cmd) -> bool, why, fix, snippet.
18
+ RULES = [
19
+ dict(id="worktree", label="Path outside isolated worktree",
20
+ test=lambda e, t, c: "isolated in the worktree" in e,
21
+ why="Claude ran inside a worktree but touched a path in the main checkout (or another repo).",
22
+ fix="Use paths relative to the worktree root, or the worktree's absolute path. Give subagents the worktree path in their brief, never the main checkout path.",
23
+ snippet="- When working in a git worktree, only use paths inside that worktree. Never cd to or edit the main checkout."),
24
+ dict(id="sleep_poll", label="Sleep-then-poll blocked",
25
+ test=lambda e, t, c: e.startswith("Blocked: sleep"),
26
+ why="Claude tried to wait with `sleep N; cat output` instead of letting background work notify it.",
27
+ fix="Run long work with run_in_background and wait for the notification, or use Monitor with an until-condition.",
28
+ snippet="- Never sleep-poll. Use run_in_background and wait for the completion notice."),
29
+ dict(id="ls_alias", label="ls aliased to eza",
30
+ test=lambda e, t, c: "--icons [<WHEN>]" in e,
31
+ why="Your shell aliases ls to eza with --icons, which swallows the next argument as its value.",
32
+ fix="Make the alias interactive-only in ~/.zshrc (`[[ -o interactive ]] && alias ls='eza --icons'`), or have Claude use `command ls`.",
33
+ snippet="- `ls` is aliased to eza; use `command ls` in shell commands."),
34
+ dict(id="cli_flags", label="Wrong CLI flags (BSD vs GNU, gh)",
35
+ test=lambda e, t, c: any(s in e for s in ("specify only one of", "unknown flag", "illegal option", "invalid option", "unrecognized option", "bad flag in substitute", "extra characters at the end", "invalid command code")),
36
+ why="Claude used GNU syntax on macOS BSD tools (sed -i, date, stat) or invalid gh flag combos.",
37
+ fix="Note in CLAUDE.md that the machine is macOS with BSD tools (sed -i '' …), or install GNU coreutils/gnu-sed.",
38
+ snippet="- macOS: BSD sed/date/stat. Use sed -i '' and check `gh <cmd> --help` for flag combos."),
39
+ dict(id="zsh_glob", label="zsh glob had no matches",
40
+ test=lambda e, t, c: "no matches found" in e,
41
+ why="zsh aborts the whole command when an unquoted glob matches nothing (bash would pass it through).",
42
+ fix="Quote glob patterns passed to find/grep/rg, or use `find`/Glob instead of shell globs. Optionally add `setopt nonomatch` to ~/.zshenv.",
43
+ snippet="- The shell is zsh: quote glob patterns (e.g. find . -name '*.ts'); unmatched globs abort the command."),
44
+ dict(id="cmd_not_found", label="Command not found",
45
+ test=lambda e, t, c: "command not found" in e or "not found in PATH" in e,
46
+ why="Claude assumed a CLI was installed or on PATH.",
47
+ fix="List the project's available tooling in CLAUDE.md (e.g. pnpm vs npm, python3 vs python). Check with `command -v` before relying on a tool.",
48
+ snippet="- Available CLIs: <list them>. Use python3 (not python). Check `command -v X` before using an unfamiliar tool."),
49
+ dict(id="no_file", label="File or directory not found",
50
+ test=lambda e, t, c: "No such file or directory" in e or "File does not exist" in e or "does not exist" in e[:200],
51
+ why="Claude guessed a path instead of looking it up first.",
52
+ fix="Locate files with Glob/ls before reading. Keep a short map of key directories in CLAUDE.md.",
53
+ snippet="- Do not guess file paths: list or glob first. Key dirs: <src/…, tests/…>."),
54
+ dict(id="edit_unread", label="Edit/Write before Read",
55
+ test=lambda e, t, c: "has not been read yet" in e,
56
+ why="The Edit/Write tool requires the file to have been read in this session.",
57
+ fix="Read the file (or the relevant range) before editing. Usually self-corrects in one step; low cost.",
58
+ snippet="- Always Read a file before Edit/Write on it."),
59
+ dict(id="edit_stale", label="File changed since read",
60
+ test=lambda e, t, c: "modified since read" in e,
61
+ why="A formatter, hook, the user or another agent changed the file after Claude read it.",
62
+ fix="Re-read before editing. If a format-on-save hook causes this, run the formatter after edits instead of on every write.",
63
+ snippet=""),
64
+ dict(id="edit_nomatch", label="Edit old_string mismatch",
65
+ test=lambda e, t, c: "String to replace not found" in e or "matches of the string to replace" in e or "No changes to make" in e,
66
+ why="Claude reconstructed old_string from memory (whitespace/indent drift) or it was not unique.",
67
+ fix="Copy old_string exactly from a fresh Read; include more surrounding context for uniqueness.",
68
+ snippet="- For Edit, copy old_string verbatim from a recent Read, with enough context to be unique."),
69
+ dict(id="user_denied", label="User rejected the action",
70
+ test=lambda e, t, c: "doesn't want to" in e or "Request interrupted by user" in e,
71
+ why="You declined or interrupted a tool call.",
72
+ fix="Look at the examples: recurring rejections point to a preference worth writing down (e.g. 'never push without asking').",
73
+ snippet="- <Your preference that Claude kept missing>"),
74
+ dict(id="perm_denied", label="Permission / safety check denied",
75
+ test=lambda e, t, c: "Permission for this" in e or "Permission to use" in e or "requested permissions" in e or "denied by" in e or "Dangerous rm" in e,
76
+ why="Auto-mode classifier, safety check or sandbox blocked the call.",
77
+ fix="Allow recurring safe commands in settings.json permissions, or steer Claude away from the blocked pattern.",
78
+ snippet=""),
79
+ dict(id="hook_block", label="Blocked by hook or harness rule",
80
+ test=lambda e, t, c: "hook error" in e or "Subagents should return" in e or "Worktree has" in e,
81
+ why="A PreToolUse hook or harness guard refused the call (e.g. sleep-polling, subagent writing files).",
82
+ fix="If the hook fires often for valid work, fix the hook; otherwise add the rule it enforces to CLAUDE.md so Claude avoids it up front.",
83
+ snippet=""),
84
+ dict(id="bad_call", label="Wrong tool name or parameters",
85
+ # Harness and tool-validation messages only: a shell call's error is "Exit code N" then the command's output,
86
+ # which can hold any of these phrases (a printed doc saying "at most"), so it never counts here.
87
+ test=lambda e, t, c: not e.lstrip().startswith("Exit code") and any(s in e for s in ("No such tool available", "InputValidationError", "Invalid parameters", "takes only", "Missing key", "also needs", "at most", "Pass either", "Pass the", "No task found", "haven't viewed", "Cannot enter worktree", "page tools can't")),
88
+ why="Claude called a tool that is not loaded, or with a malformed input.",
89
+ fix="Mostly harness/skill-doc issues. If one tool dominates, its instructions or skill are unclear; tighten them.",
90
+ snippet=""),
91
+ dict(id="infra", label="Harness / connection failure",
92
+ test=lambda e, t, c: any(s in e for s in ("AbortError", "no active turn", "WebSocket is not defined", "session ended", "fetch failed", "snapshot timed out", "Stream closed")),
93
+ why="Transient app or MCP connection issue, not Claude's reasoning.",
94
+ fix="Not fixable by prompting. Update the app / MCP server if it spikes.",
95
+ snippet=""),
96
+ dict(id="timeout", label="Command timed out",
97
+ test=lambda e, t, c: "timed out" in e.lower() or "Command timed out" in e,
98
+ why="A long-running command hit the tool timeout.",
99
+ fix="Run servers and watchers in the background; pass longer timeouts for slow test suites.",
100
+ snippet="- Run dev servers and long test suites with run_in_background."),
101
+ dict(id="search_empty", label="grep/rg found nothing (exit 1)",
102
+ test=lambda e, t, c: re.match(r"\s*(cd [^&;]+(&&|;)\s*)?(grep|rg|egrep|git grep)\b", c or "") is not None and e.strip().startswith("Exit code 1"),
103
+ why="grep/rg exit 1 means 'no match'; the harness reports it as an error.",
104
+ fix="Harmless signal. Append `|| true` when an empty result is expected, or prefer the Grep tool.",
105
+ snippet="- grep/rg exit 1 means no matches; use the Grep tool or append `|| true`."),
106
+ dict(id="chained", label="Chained command: one step failed",
107
+ test=lambda e, t, c: e.lstrip().startswith("Exit code") and len(e) > 80 and not re.search(r"(?i)error|fatal|fail|denied|not found|invalid|cannot|unable|traceback|panic|conflict|exception", e),
108
+ why="A `a; b; c` or `&&` chain produced useful output but a trailing probe (often ls/grep on an optional path) exited non-zero, so the whole call is flagged.",
109
+ fix="Append `|| true` to optional probes, or split exploratory commands. Often harmless noise.",
110
+ snippet="- End optional probes in chained commands with `|| true` so the call does not report failure."),
111
+ dict(id="tests", label="Tests / build / lint failed",
112
+ test=lambda e, t, c: TEST_CMD.search(c or "") is not None,
113
+ why="Real failures in the project's checks; often expected while iterating.",
114
+ fix="Track whether the same suite fails repeatedly. Flaky or slow suites deserve a CLAUDE.md note on how to run a single test.",
115
+ snippet="- Run a single test with: <command>. Full suite: <command>."),
116
+ dict(id="git", label="git / gh error",
117
+ test=lambda e, t, c: "fatal:" in e or re.search(r"\b(git|gh)\b", c or "") is not None,
118
+ why="git state was not what Claude assumed (branch, remote, dirty tree, auth).",
119
+ fix="Check `git status` / current branch before branch-changing commands.",
120
+ snippet="- Run git status before git operations that change branches or history."),
121
+ dict(id="python", label="Script error (Python/Node)",
122
+ test=lambda e, t, c: "Traceback" in e or "SyntaxError" in e or "TypeError" in e or "ReferenceError" in e,
123
+ why="An ad-hoc inline script crashed (often bad assumptions about data shape).",
124
+ fix="Inspect input shape before writing parsing scripts; write longer scripts to a file instead of heredocs.",
125
+ snippet=""),
126
+ dict(id="os_perm", label="OS permission / sandbox",
127
+ test=lambda e, t, c: "Operation not permitted" in e or "Permission denied" in e or "sandbox" in e.lower() or "EPERM" in e,
128
+ why="Sandbox or file permissions blocked the command.",
129
+ fix="Use the scratchpad dir for temp files; add needed paths to sandbox allow-lists.",
130
+ snippet=""),
131
+ dict(id="exit_other", label="Other non-zero exit",
132
+ test=lambda e, t, c: e.lstrip().startswith("Exit code"),
133
+ why="Shell command failed for another reason. Open examples to spot new patterns.",
134
+ fix="Review examples; promote recurring patterns to their own rule in categorize.py.",
135
+ snippet=""),
136
+ dict(id="other", label="Other",
137
+ test=lambda e, t, c: True,
138
+ why="Uncategorized tool error.",
139
+ fix="Review examples; add a rule in categorize.py when a pattern repeats.",
140
+ snippet=""),
141
+ ]
142
+
143
+
144
+ def text_of(content):
145
+ if isinstance(content, str):
146
+ return content
147
+ if isinstance(content, list):
148
+ return "\n".join(x.get("text", "") for x in content if isinstance(x, dict))
149
+ return str(content or "")
150
+
151
+
152
+ def summarize_input(tool, inp):
153
+ if not isinstance(inp, dict):
154
+ return ""
155
+ for k in ("command", "file_path", "pattern", "url", "path", "query", "skill", "prompt"):
156
+ if k in inp and isinstance(inp[k], str):
157
+ return inp[k]
158
+ return json.dumps(inp)[:300]
159
+
160
+
161
+ # input_pattern: a shell script wrapped as `bash -lc '…'`, and what may come before the command itself: a subshell's
162
+ # "(", `cd … &&` or `cd …;`, env assignments and sudo with its flags.
163
+ SHELL_WRAP = re.compile(r"""\s*(?:\S*/)?(?:ba|z)?sh\s+-l?c\s+(['"])(.*)\1\s*$""", re.S)
164
+ SHELL_LEAD = re.compile(r"\s*(?:\(\s*|cd\s+[^&;|]*(?:&&|;)\s*|[A-Za-z_]\w*=\S*\s+|sudo\s+(?:-\S+\s+)*)")
165
+ FILE_TOOLS = {"Read", "Edit", "Write", "NotebookEdit", "apply_patch"}
166
+ SEARCH_TOOLS = {"Grep", "Glob"}
167
+ SEARCH_CUT = 40
168
+
169
+
170
+ def input_pattern(tool, summary):
171
+ """The group a call's input_summary falls in on the tool inspector: a shell command's first word, a file's extension
172
+ (its name when it has none), a search pattern cut to SEARCH_CUT, a URL's host, "search" for a web search, else "other"."""
173
+ summary = (summary or "").strip()
174
+ if tool in SHELL_TOOLS:
175
+ cmd = summary
176
+ while m := SHELL_WRAP.match(cmd) or SHELL_LEAD.match(cmd):
177
+ cmd = m.group(2) if m.re is SHELL_WRAP else cmd[m.end():]
178
+ word = re.match(r"[^\s;&|()<>]+", cmd)
179
+ return word.group(0) if word else "other"
180
+ if tool in FILE_TOOLS:
181
+ name = os.path.basename(summary.split(", ")[0]) # apply_patch lists every changed file
182
+ return (os.path.splitext(name)[1] or name) if name else "other"
183
+ if tool in SEARCH_TOOLS:
184
+ return summary[:SEARCH_CUT] or "other"
185
+ if tool == "WebFetch":
186
+ try:
187
+ return urlsplit(summary).hostname or "other"
188
+ except ValueError: # such as an unclosed IPv6 bracket
189
+ return "other"
190
+ if tool in ("WebSearch", "web_search"):
191
+ return "search"
192
+ return "other"
193
+
194
+
195
+ def categorize(err, tool, cmd):
196
+ return next(r["id"] for r in RULES if r["test"](err, tool, cmd))
197
+
198
+
199
+ def error_text(content):
200
+ return text_of(content).replace("<tool_use_error>", "").replace("</tool_use_error>", "").strip()