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,479 @@
1
+ """aut CLI.
2
+
3
+ aut scan incremental: read new rows since the watermark, push, advance
4
+ aut scan --dry-run parse + normalize + AGGREGATE, print a report, send/commit nothing
5
+ aut backfill reset the watermark for the selected agents, then scan everything
6
+ aut backfill --sessions-only [--dry-run]
7
+ re-read all history and send ONLY session rows; watermark untouched
8
+ aut backfill --activity-only [--dry-run]
9
+ the same for activity rows (steers, commits, turns, ...); never usage
10
+ aut status show config + watermark state
11
+ aut doctor --json inspect source coverage without writing or connecting
12
+ aut export [--out F] write all usage as CSV (bulk load, offline bridge); never the watermark
13
+ aut sync-prices [--out F]
14
+ refresh the API-equivalent model price map
15
+ aut time add --start <local> --end <local> | --minutes N [--at <local end>] [--not-relevant]
16
+ record a manual active-time interval (needs transport.pg_dsn)
17
+ aut outcomes [--fetch] [--dry-run]
18
+ score every commit row against the local clones -> agents.commit_outcome
19
+ aut outcome <shipped|ruled-out|open> [--session ID]
20
+ the manual outcome of this project's newest interactive session
21
+ aut history-steers [--dry-run]
22
+ daily steer estimates for lost 2026 logs, from the CLI history files
23
+ aut episodes review [--month YYYY-MM]
24
+ hand-check a month's episodes on a local page -> agents.episode_correction
25
+ aut inspect --episode ID | --day YYYY-MM-DD | --label UNIT_ID
26
+ why an episode, a day's episodes or a label exist, on a local evidence page
27
+ (its linked correction form writes agents.episode_correction)
28
+ aut label run [--task T] [--since YYYY-MM-DD] [--dry-run]
29
+ a local model labels new units (optional extra aut[label]) -> label rows
30
+ aut label backfill --task T --days N
31
+ the same over the last N days; the nightly watermark is not moved back
32
+ aut label replay --task T --since YYYY-MM-DD --until YYYY-MM-DD
33
+ freeze a private historical job and preview its counts, without scoring
34
+ aut label replay --job ID [--apply] [--budget-s N]
35
+ preview or resume that job; separate progress, no teacher calls
36
+ aut label teach --task T --n N [--budget-usd X]
37
+ teacher (silver) labels for a stratified sample -> eval/<task>.silver.jsonl
38
+ aut label review [--task T]
39
+ label gold answers on a local page -> eval/<task>.jsonl (never text)
40
+ aut label eval --task T [--final --model M]
41
+ bake-off on gold -> saved scores, eval record, one table per task
42
+ aut label choose --task T [--model M] | train-encoder --task T
43
+ the table, or M's saved result -> label.json; the encoder
44
+ aut git-days [--dry-run] [--allow-lower]
45
+ your commits per ledger day from every clone, counts only
46
+ -> agents.git_commit_day ([git_days]; `aut scan` runs it daily if enabled)
47
+ aut backup [--check] encrypted restic backup of the logs, salt and label files ([backup] in
48
+ config.toml); --check verifies the repository and sends nothing
49
+
50
+ The dry-run report doubles as the accuracy check: it prints per-agent, per-model token
51
+ sums straight from your real logs.
52
+ """
53
+
54
+ from __future__ import annotations
55
+
56
+ from pathlib import Path
57
+
58
+ import argparse
59
+ import json
60
+ import os
61
+ import sys
62
+ from datetime import date, timedelta
63
+ from typing import Sequence
64
+
65
+ from . import backup, cursor_run, git_days, inspector, manual_time, outcomes, pricing, review, scan
66
+ from .collectors import REGISTRY
67
+ from .config import (ALL_AGENTS, LABEL_DAYS, LABEL_DECISION_TASKS, LABEL_TASK_NAMES, AutError,
68
+ Config, load_config, config_path)
69
+ from .push import is_operational_failure, outbox_status, redacted_error, replay_outbox, webhook_url_allowed
70
+ from .state import collector_wm, load_state
71
+
72
+
73
+ def _fail_if_partial(what: str, failed: set[str]) -> None:
74
+ """A one-shot command has no heartbeat, so its exit code is what stops `aut export && load`."""
75
+ if failed:
76
+ raise AutError(f"{what}: partial, could not fully read {', '.join(sorted(failed))} "
77
+ "(reasons above)")
78
+
79
+
80
+ def cmd_scan(cfg: Config, agents: Sequence[str], args: argparse.Namespace) -> None:
81
+ report = scan.run_scan(cfg, agents, dry_run=args.dry_run)
82
+ scan.print_scan(cfg, report, dry_run=args.dry_run)
83
+ if args.cmd == "scan" and not args.dry_run:
84
+ if args.git_defer_remotes_until:
85
+ git_days.run_if_due(cfg, defer_remotes_until=args.git_defer_remotes_until)
86
+ else:
87
+ git_days.run_if_due(cfg) # the launchd scan carries the daily git count
88
+
89
+
90
+ def cmd_git_days(cfg: Config, args: argparse.Namespace) -> None:
91
+ git_days.print_report(git_days.run(cfg, dry_run=args.dry_run, allow_lower=args.allow_lower,
92
+ local_only=args.local_only,
93
+ defer_remotes_until=args.git_defer_remotes_until),
94
+ dry_run=args.dry_run)
95
+
96
+
97
+ def cmd_backfill(cfg: Config, agents: Sequence[str], args: argparse.Namespace) -> None:
98
+ if args.sessions_only or args.activity_only:
99
+ counts = scan.run_history_backfill(cfg, agents, dry_run=args.dry_run,
100
+ sessions=args.sessions_only, activity=args.activity_only)
101
+ scan.print_history_backfill(counts, dry_run=args.dry_run, sessions=args.sessions_only,
102
+ activity=args.activity_only)
103
+ _fail_if_partial("backfill", counts["failed"])
104
+ return
105
+ scan.reset_watermarks(agents)
106
+ print(f"watermark reset for: {', '.join(agents)}")
107
+ cmd_scan(cfg, agents, args)
108
+
109
+
110
+ def cmd_export(cfg: Config, agents: Sequence[str], args: argparse.Namespace) -> None:
111
+ out = open(args.out, "w", newline="", encoding="utf-8") if args.out else sys.stdout
112
+ try:
113
+ written, skipped, failed = scan.run_export(cfg, agents, out)
114
+ finally:
115
+ if args.out:
116
+ out.close()
117
+ scan.print_export(written, skipped, args.out)
118
+ _fail_if_partial("export", failed)
119
+
120
+
121
+ def cmd_status(cfg: Config, agents: Sequence[str], args: argparse.Namespace) -> None:
122
+ state = load_state()
123
+ print(f"machine : {cfg.machine}")
124
+ print(f"agents : {', '.join(agents)}")
125
+ if cfg.has_webhook and not cfg.webhook_secret:
126
+ webhook_state = "url set but SECRET MISSING (scan will refuse)"
127
+ elif cfg.has_webhook and not webhook_url_allowed(cfg.webhook_url or ""):
128
+ webhook_state = "url NOT ALLOWED: https://, or http:// to localhost (scan will refuse)"
129
+ else:
130
+ webhook_state = "configured" if cfg.has_webhook else "NOT set"
131
+ print(f"webhook : {webhook_state}")
132
+ print(f"pg fallback : {'configured' if cfg.has_pg else 'not set'}")
133
+ print(f"backup : {backup.describe()}")
134
+ pending = outbox_status()
135
+ print(f"delivery queue: {sum(pending.values())} pending rows"
136
+ + (f" ({', '.join(f'{kind}: {n}' for kind, n in sorted(pending.items()))})" if pending else ""))
137
+ print("coverage : inspect known and registered sources with aut doctor --json")
138
+ print("watermarks :")
139
+ for name in agents:
140
+ print(f" {name:<12} {REGISTRY[name].describe(cfg, collector_wm(state, name))}")
141
+
142
+
143
+ def cmd_doctor(cfg: Config, args: argparse.Namespace) -> None:
144
+ from .coverage import build_report
145
+
146
+ report = build_report(cfg)
147
+ if args.json:
148
+ print(json.dumps(report, indent=2, sort_keys=True))
149
+ return
150
+ print(f"coverage: {len(report['sources'])} inspected source(s), "
151
+ f"{len(report['issues'])} reported issue(s)")
152
+ print("scope: known and registered sources; completeness remains evidence-specific")
153
+ for issue in report["issues"]:
154
+ print(f" {issue['source_id']}: {issue['code']}")
155
+ print("Use aut doctor --json for capabilities, evidence and limits.")
156
+
157
+
158
+ def cmd_time_add(cfg: Config, args: argparse.Namespace) -> None:
159
+ span = manual_time.ManualSpan(args.start, args.end, args.minutes, args.at)
160
+ manual_time.print_time_add(manual_time.run_time_add(cfg, span, not_relevant=args.not_relevant))
161
+
162
+
163
+ def cmd_outcomes(cfg: Config, args: argparse.Namespace) -> None:
164
+ report = outcomes.run_outcomes(cfg, refresh=args.fetch or cfg.outcome_fetch,
165
+ dry_run=args.dry_run)
166
+ outcomes.print_outcomes(report, dry_run=args.dry_run)
167
+ if not args.dry_run and any(report.get(k) for k in outcomes._READ_FAILURES):
168
+ raise AutError("outcomes: some reads failed; completed results saved, retry remaining work")
169
+
170
+
171
+ def cmd_outcome(cfg: Config, args: argparse.Namespace) -> None:
172
+ dsn = cfg.require_pg("outcome")
173
+ row = outcomes.build_manual_outcome(cfg, args.outcome, os.getcwd(), args.session)
174
+ outcomes.insert_manual_outcome(dsn, row)
175
+ print(f"marked session {row['session_id'][:8]} {row['outcome']}")
176
+
177
+
178
+ def cmd_inspect(cfg: Config, args: argparse.Namespace) -> None:
179
+ selected: tuple[inspector.Selector, str] = (
180
+ ("episode", args.episode) if args.episode is not None else
181
+ ("day", args.day) if args.day is not None else ("label", args.label))
182
+ inspector.print_inspect(inspector.run_inspect(cfg, *selected))
183
+
184
+
185
+ def cmd_episodes(cfg: Config, args: argparse.Namespace) -> None:
186
+ review.print_review(review.run_episode_review(cfg, args.month))
187
+
188
+
189
+ # The label modules are imported where used, so every other command skips loading their code (a
190
+ # test holds the CLI to that). The collectors load regardless, for scan and REGISTRY above.
191
+ def _label_run(cfg: Config, args: argparse.Namespace) -> None:
192
+ """run | backfill: label new units, or one task over the last N days."""
193
+ from .label import run as label_run
194
+ from .label.core import local_midnight
195
+ tasks: list[str] | None
196
+ if args.label_cmd == "backfill":
197
+ since = date.today() - timedelta(days=args.days)
198
+ tasks, dry = [args.task], False
199
+ else:
200
+ since, tasks, dry = args.since, [args.task] if args.task else None, args.dry_run
201
+ report = label_run.run_label(cfg, tasks, local_midnight(since) if since else None,
202
+ dry_run=dry, local_estimates=getattr(args, "local_estimates", False))
203
+ label_run.print_report(report, dry_run=dry)
204
+ failed = [name for name, c in report.items()
205
+ if any(c.get(flag) for flag in ("failed", "unavailable", "cut"))]
206
+ if failed:
207
+ raise AutError(f"label: could not run {', '.join(failed)} to completion; "
208
+ "saved progress will resume (reasons above)")
209
+
210
+
211
+ def _label_bakeoff(cfg: Config, args: argparse.Namespace) -> None:
212
+ """eval | choose | train-encoder: the bake-off on the gold labels."""
213
+ from .label import bakeoff
214
+ if args.label_cmd == "eval":
215
+ if args.final or args.model:
216
+ if not (args.final and args.model):
217
+ raise AutError("label eval: --final and --model go together")
218
+ bakeoff.print_final(bakeoff.run_final(cfg, args.task, args.model, args.days))
219
+ else:
220
+ bakeoff.print_eval(cfg, args.task, bakeoff.run_eval(cfg, args.task, args.days))
221
+ elif args.label_cmd == "choose":
222
+ chosen = bakeoff.choose(cfg, args.task, args.model)
223
+ if chosen:
224
+ bakeoff.print_choose(args.task, chosen)
225
+ else:
226
+ bakeoff.print_train_encoder(args.task, bakeoff.train_encoder(cfg, args.task, args.days))
227
+
228
+
229
+ def cmd_label(cfg: Config, args: argparse.Namespace) -> None:
230
+ if args.label_cmd == "import-baseline":
231
+ from .label import baseline
232
+ print(json.dumps(baseline.run(cfg, Path(args.path), apply=args.apply), sort_keys=True))
233
+ elif args.label_cmd == "replay":
234
+ from .label import replay
235
+ if not 1 <= args.budget_s <= 3600:
236
+ raise AutError("label replay: budget must be between 1 and 3600 seconds")
237
+ if args.job:
238
+ if args.task or args.since or args.until:
239
+ raise AutError("label replay: a saved job cannot be combined with a new range")
240
+ result = replay.resume(cfg, args.job, apply=args.apply, budget_s=args.budget_s)
241
+ else:
242
+ if args.apply or not (args.task and args.since and args.until):
243
+ raise AutError("label replay: preview a task and date range, then apply its saved job")
244
+ result = replay.prepare(cfg, args.task, args.since, args.until)
245
+ print(json.dumps(result, sort_keys=True))
246
+ elif args.label_cmd in ("run", "backfill"):
247
+ _label_run(cfg, args)
248
+ elif args.label_cmd == "teach":
249
+ from .label import teach
250
+ teach.print_teach(args.task, teach.run_teach(cfg, args.task, args.n,
251
+ budget_usd=args.budget_usd, days=args.days,
252
+ sonnet_only=args.sonnet_only),
253
+ args.budget_usd)
254
+ elif args.label_cmd == "review":
255
+ from .label import gold
256
+ gold.print_review(gold.run_gold_review(cfg, args.task, args.days))
257
+ else:
258
+ _label_bakeoff(cfg, args)
259
+
260
+
261
+ def cmd_history_steers(cfg: Config, args: argparse.Namespace) -> None:
262
+ from . import history_steers
263
+ c = history_steers.run(cfg, args.dry_run)
264
+ print(f"history-steers {'DRY-RUN (nothing written)' if args.dry_run else 'written'}: "
265
+ f"{json.dumps(dict(c))}")
266
+
267
+
268
+ def cmd_backup(cfg: Config, args: argparse.Namespace) -> None:
269
+ backup.run_backup(cfg, check=args.check)
270
+
271
+
272
+ def cmd_sync_prices(args: argparse.Namespace) -> None:
273
+ out = args.out or str(config_path().parent / "model_prices.json")
274
+ n = pricing.sync_prices(out, litellm_url=args.litellm_url, models_dev_url=args.models_dev_url,
275
+ genai_prices_url=args.genai_prices_url)
276
+ print(f"synced {n} model prices -> {out}", file=sys.stderr)
277
+
278
+
279
+ def cmd_cursor_run(args: argparse.Namespace) -> None:
280
+ cursor_run.run(args.model, args.workspace, sys.stdin)
281
+
282
+
283
+ def cmd_scan_job(args: argparse.Namespace) -> None:
284
+ from . import scheduled
285
+ code = scheduled.main()
286
+ if code:
287
+ raise SystemExit(code)
288
+
289
+
290
+ def cmd_delivery_retry(cfg: Config, args: argparse.Namespace) -> None:
291
+ print(f"delivery queue: sent {replay_outbox(cfg)} rows")
292
+
293
+
294
+ _NO_CONFIG_COMMANDS = {"sync-prices": cmd_sync_prices, "cursor-run": cmd_cursor_run,
295
+ "scan-job": cmd_scan_job}
296
+ _AGENT_COMMANDS = {"scan": cmd_scan, "backfill": cmd_backfill, "export": cmd_export,
297
+ "status": cmd_status}
298
+ _COMMANDS = {"time": cmd_time_add, "outcomes": cmd_outcomes, "outcome": cmd_outcome,
299
+ "inspect": cmd_inspect, "episodes": cmd_episodes, "label": cmd_label,
300
+ "history-steers": cmd_history_steers, "backup": cmd_backup, "git-days": cmd_git_days,
301
+ "retry-delivery": cmd_delivery_retry, "doctor": cmd_doctor}
302
+
303
+
304
+ def _build_parser() -> argparse.ArgumentParser:
305
+ parser = argparse.ArgumentParser(prog="aut", description="passive coding-agent usage, activity, active-time and outcome tracker")
306
+ agents_help = "comma-separated subset override (default: config)"
307
+ parser.add_argument("--agents", help=f"{agents_help}; for scan, backfill, export and status")
308
+ parser.add_argument('--git-defer-remotes-until', type=date.fromisoformat,
309
+ help='skip Git SSH sources before this ledger date; scan/git-days only')
310
+ sub = parser.add_subparsers(dest="cmd", required=True)
311
+ from .improve.cli import register
312
+ register(sub)
313
+ from .observation_cli import register as register_observations
314
+ register_observations(sub)
315
+ sub.add_parser("scan-job", help="run the locked scheduled scan and retry unfinished daily jobs")
316
+ sub.add_parser("retry-delivery", help="send deferred session/activity/time rows using pg_dsn")
317
+ p_scan = sub.add_parser("scan", help="push new usage since the watermark")
318
+ p_scan.add_argument("--dry-run", action="store_true", help="parse + report, send nothing")
319
+ p_back = sub.add_parser("backfill",
320
+ help="reset watermark for selected agents, then scan all history")
321
+ p_back.add_argument("--sessions-only", action="store_true",
322
+ help="send only session rows for all history; watermark untouched")
323
+ p_back.add_argument("--activity-only", action="store_true",
324
+ help="send only activity rows for all history; watermark untouched")
325
+ p_back.add_argument("--dry-run", action="store_true",
326
+ help="with --sessions-only/--activity-only: counts only")
327
+ p_status = sub.add_parser("status", help="show config + watermark state")
328
+ p_doctor = sub.add_parser("doctor", help="inspect source coverage without writing or connecting")
329
+ p_doctor.add_argument("--json", action="store_true", help="print the private coverage report")
330
+ p_export = sub.add_parser("export", help="write all usage as CSV (bulk load / offline bridge)")
331
+ p_export.add_argument("--out", help="output CSV file (default: stdout)")
332
+ for sp in (p_scan, p_back, p_status, p_export): # accepted after the subcommand too
333
+ sp.add_argument("--agents", default=argparse.SUPPRESS, help=agents_help)
334
+ p_sync = sub.add_parser("sync-prices", help="refresh the API-equivalent model price map")
335
+ p_sync.add_argument("--out", help="output JSON (default: <config-dir>/model_prices.json)")
336
+ p_sync.add_argument("--litellm-url", default=pricing.LITELLM_URL)
337
+ p_sync.add_argument("--models-dev-url", default=pricing.MODELS_DEV_URL)
338
+ p_sync.add_argument("--genai-prices-url", default=pricing.GENAI_PRICES_URL)
339
+ p_cursor = sub.add_parser("cursor-run", help="run a scripted Cursor request with a registered origin")
340
+ p_cursor.add_argument("--model", required=True, help="explicit Cursor model identifier")
341
+ p_cursor.add_argument("--workspace", required=True, help="workspace for this scripted request")
342
+ p_time = sub.add_parser("time", help="manual active time")
343
+ time_sub = p_time.add_subparsers(dest="time_cmd", required=True)
344
+ p_tadd = time_sub.add_parser("add", help="record one manual interval (local times)")
345
+ p_tadd.add_argument("--start", help="local start, e.g. '2026-11-03 09:00'")
346
+ p_tadd.add_argument("--end", help="local end")
347
+ p_tadd.add_argument("--minutes", type=int, help="length in minutes, ending at --at")
348
+ p_tadd.add_argument("--at", help="local end for --minutes (default: now)")
349
+ p_tadd.add_argument("--not-relevant", action="store_true",
350
+ help="not work-relevant (default: relevant)")
351
+ p_outs = sub.add_parser("outcomes", help="score commit rows against the local clones")
352
+ p_outs.add_argument("--fetch", action="store_true",
353
+ help="git fetch the clones and ask gh first (config: outcome_fetch)")
354
+ p_outs.add_argument("--dry-run", action="store_true", help="count states, write nothing, no fetch or gh")
355
+ p_hist = sub.add_parser("history-steers",
356
+ help="daily steer estimates for lost 2026 logs, from CLI history")
357
+ p_hist.add_argument("--dry-run", action="store_true", help="count, write nothing")
358
+ p_bak = sub.add_parser("backup", help="encrypted restic backup of the logs ([backup] config)")
359
+ p_bak.add_argument("--check", action="store_true",
360
+ help="verify the repository (restic check); back up nothing")
361
+ p_git = sub.add_parser("git-days",
362
+ help="your commits per day from every clone ([git_days] config)")
363
+ p_git.add_argument('--local-only', action='store_true', help='do not contact Git SSH sources')
364
+ p_git.add_argument("--dry-run", action="store_true",
365
+ help="scan and print totals per year, write nothing")
366
+ p_git.add_argument("--allow-lower", action="store_true",
367
+ help="also rewrite stored days whose count went down (a deliberate fix)")
368
+ p_out = sub.add_parser("outcome", help="mark this project's newest session's outcome")
369
+ p_out.add_argument("outcome", choices=["shipped", "ruled-out", "open"])
370
+ p_out.add_argument("--session", help="the session id (default: newest interactive here)")
371
+ p_eps = sub.add_parser("episodes", help="episodes")
372
+ eps_sub = p_eps.add_subparsers(dest="eps_cmd", required=True)
373
+ p_rev = eps_sub.add_parser("review", help="hand-check one month's episodes (local page)")
374
+ p_rev.add_argument("--month", help="YYYY-MM (default: the last completed month)")
375
+ p_ins = sub.add_parser("inspect", help="why an episode, a day or a label exists (local page)")
376
+ ins = p_ins.add_mutually_exclusive_group(required=True)
377
+ ins.add_argument("--episode", help="episode id (a prefix is enough)")
378
+ ins.add_argument("--day", help="local YYYY-MM-DD: the episodes with a member row that day")
379
+ ins.add_argument("--label", help="a label's unit_id (steer event id, <episode>:<date>, ...)")
380
+ p_lab = sub.add_parser("label", help="local model labels (optional extra aut[label])")
381
+ lab_sub = p_lab.add_subparsers(dest="label_cmd", required=True)
382
+ p_base = lab_sub.add_parser("import-baseline", help="preview provisional historical estimates")
383
+ p_base.add_argument("path", help="private working-baseline JSON file")
384
+ p_base.add_argument("--apply", action="store_true", help="append estimates to the sink")
385
+ p_lrun = lab_sub.add_parser("run", help="label new units since the watermark")
386
+ p_lrun.add_argument("--task", choices=LABEL_TASK_NAMES, help="one task (default: label_tasks)")
387
+ p_lrun.add_argument("--since", type=date.fromisoformat,
388
+ help="local YYYY-MM-DD to start from instead of the watermark")
389
+ p_lrun.add_argument("--dry-run", action="store_true", help="score and count, write nothing")
390
+ p_lrun.add_argument("--local-estimates", action="store_true",
391
+ help="apply saved local decision recipes as separate provisional estimates")
392
+ p_lback = lab_sub.add_parser("backfill", help="label one task over the last N days")
393
+ p_lback.add_argument("--task", choices=LABEL_TASK_NAMES, required=True)
394
+ p_lback.add_argument("--days", type=int, required=True)
395
+ p_replay = lab_sub.add_parser("replay", help="preview or resume a private historical local job")
396
+ p_replay.add_argument("--task", choices=("steer_intent", "work_category", "soft_outcome", "writing_activity"))
397
+ p_replay.add_argument("--since", type=date.fromisoformat, help="first local date, inclusive")
398
+ p_replay.add_argument("--until", type=date.fromisoformat, help="last local date, exclusive")
399
+ p_replay.add_argument("--job", help="saved private job ID instead of a new range")
400
+ p_replay.add_argument("--apply", action="store_true", help="score and deliver the saved job")
401
+ p_replay.add_argument("--budget-s", type=int, default=600, help="1 to 3600 seconds per resume")
402
+ p_teach = lab_sub.add_parser("teach", help="teacher (silver) labels for a stratified sample")
403
+ p_teach.add_argument("--task", choices=LABEL_DECISION_TASKS, required=True)
404
+ p_teach.add_argument("--n", type=int, required=True, help="units to label this run")
405
+ p_teach.add_argument("--budget-usd", type=float, default=5.0,
406
+ help="cap on this run's Sonnet spend (default 5)")
407
+ p_teach.add_argument("--sonnet-only", action="store_true",
408
+ help="skip the local teacher, and every unit Sonnet may not read")
409
+ p_lrev = lab_sub.add_parser("review", help="label gold answers on a local page")
410
+ p_lrev.add_argument("--task", choices=LABEL_DECISION_TASKS)
411
+ for name, text in (("eval", "score every backend on the gold labels; print the table"),
412
+ ("choose", "print the table, or write --model's result to label.json"),
413
+ ("train-encoder", "fit the small encoder on gold + silver")):
414
+ lab_sub.add_parser(name, help=text).add_argument("--task", choices=LABEL_DECISION_TASKS,
415
+ required=True)
416
+ for sp in (p_teach, p_lrev, lab_sub.choices["eval"], lab_sub.choices["train-encoder"]):
417
+ sp.add_argument("--days", type=int, default=LABEL_DAYS,
418
+ help=f"window of whole past days the units come from (default {LABEL_DAYS})")
419
+ lab_sub.choices["eval"].add_argument("--final", action="store_true",
420
+ help="score --model on the final test days")
421
+ for name in ("eval", "choose"):
422
+ lab_sub.choices[name].add_argument("--model", help="a name from the eval table")
423
+ return parser
424
+
425
+
426
+ def main(argv: list[str] | None = None) -> int:
427
+ parser = _build_parser()
428
+ args = parser.parse_args(argv)
429
+ try:
430
+ _dispatch(parser, args)
431
+ except AutError as exc:
432
+ print(exc, file=sys.stderr)
433
+ return 1
434
+ except Exception as exc:
435
+ if not is_operational_failure(exc): # a bug keeps its traceback
436
+ raise
437
+ print(f"aut: {redacted_error(exc)}", file=sys.stderr)
438
+ return 1
439
+ return 0
440
+
441
+
442
+ def _dispatch(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
443
+ if args.git_defer_remotes_until and args.cmd not in ('scan', 'git-days'):
444
+ parser.error('--git-defer-remotes-until applies only to scan and git-days')
445
+ if args.agents and args.cmd not in _AGENT_COMMANDS: # it would run over everything
446
+ parser.error(f"--agents does not apply to {args.cmd}")
447
+ if args.cmd == "improve":
448
+ from .improve.cli import run
449
+ run(args)
450
+ return
451
+ if args.cmd == "observe":
452
+ from .observation_cli import run as run_observation
453
+ result = run_observation(args)
454
+ if result is not None:
455
+ print(result if isinstance(result, str) else json.dumps(result, sort_keys=True))
456
+ return
457
+ if args.cmd in _NO_CONFIG_COMMANDS:
458
+ _NO_CONFIG_COMMANDS[args.cmd](args)
459
+ return
460
+
461
+ cfg = load_config()
462
+ if args.cmd in _COMMANDS:
463
+ _COMMANDS[args.cmd](cfg, args)
464
+ return
465
+ agents = cfg.agents
466
+ if args.agents:
467
+ agents = tuple(a.strip() for a in args.agents.split(",") if a.strip())
468
+ bad = [a for a in agents if a not in ALL_AGENTS]
469
+ if bad:
470
+ parser.error(f"unknown agent(s): {bad}; valid = {list(ALL_AGENTS)}")
471
+ if args.cmd == "backfill" and args.dry_run and not (args.sessions_only or args.activity_only):
472
+ parser.error("backfill --dry-run needs --sessions-only or --activity-only (a plain "
473
+ "backfill resets the watermark; preview it with `aut scan --dry-run`)")
474
+
475
+ _AGENT_COMMANDS[args.cmd](cfg, agents, args)
476
+
477
+
478
+ if __name__ == "__main__":
479
+ sys.exit(main())
@@ -0,0 +1,115 @@
1
+ """Collector registry. Each collector exposes:
2
+
3
+ collect(cfg, wm) -> Iterator[(events, advance_watermark)]
4
+
5
+ where each yield is (events for one source unit, a callback that advances that unit's
6
+ watermark). The runner pushes `events`, and only on a successful push calls the callback.
7
+ `wm` belongs to the collector: only its `describe` reads the keys, for `aut status`.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import sys
14
+ from dataclasses import dataclass
15
+ from datetime import datetime, timezone
16
+ from typing import Any, Callable, Generator, Iterator
17
+
18
+ from ..config import Config
19
+ from ..event import Batch, parse_ts
20
+ from . import activitywatch, claude_code, codex, cursor, cursor_api, cursor_cli, cursor_sdk, pi
21
+ from . import generic_sdk, t3
22
+ from ._util import FileSnapshot, describe_files, describe_full_scan, file_snapshot
23
+
24
+ # Each collect() pass reads at most _MAX_LINES (50k) new lines per file (see collectors/_util.py),
25
+ # so a consumer drains by re-running collect() until the watermark stops advancing. Bound the loop
26
+ # far above any real file so a misbehaving collector can't spin forever (50k lines/pass * this =
27
+ # an absurd ceiling, never hit in practice).
28
+ MAX_DRAIN_PASSES = 100_000
29
+
30
+ Collect = Callable[[Config, dict[str, Any]], Iterator[Batch]]
31
+ _USAGE_ONLY = frozenset({"usage"}) # no session or activity rows, see CONTRACT.md
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class Collector:
36
+ collect: Collect
37
+ describe: Callable[[Config, dict[str, Any]], str] = describe_files # one line for `aut status`
38
+ after_scan: Callable[[Config], object] | None = None # never run by a dry run
39
+ # What it can emit: a one-shot command is partial only if a collector it keeps rows from failed.
40
+ rows: frozenset[str] = frozenset({"usage", "session", "activity"})
41
+
42
+
43
+ REGISTRY: dict[str, Collector] = {
44
+ t3.NAME: Collector(t3.collect, t3.describe, rows=frozenset({"usage", "session", "activity"})),
45
+ generic_sdk.NAME: Collector(generic_sdk.collect, generic_sdk.describe, rows=_USAGE_ONLY),
46
+ claude_code.NAME: Collector(claude_code.collect),
47
+ codex.NAME: Collector(codex.collect),
48
+ cursor.NAME: Collector(cursor.collect, describe_full_scan, rows=_USAGE_ONLY),
49
+ cursor_sdk.NAME: Collector(cursor_sdk.collect, describe_full_scan, rows=_USAGE_ONLY),
50
+ cursor_api.NAME: Collector(cursor_api.collect, cursor_api.describe, rows=_USAGE_ONLY),
51
+ cursor_cli.NAME: Collector(cursor_cli.collect, cursor_cli.describe),
52
+ pi.NAME: Collector(pi.collect),
53
+ activitywatch.NAME: Collector(activitywatch.collect, activitywatch.describe,
54
+ activitywatch.purge, rows=frozenset({"time"})),
55
+ }
56
+
57
+
58
+ def _stamped(collect: Collect, cfg: Config, wm: dict[str, Any],
59
+ snapshot: FileSnapshot) -> Generator[Batch, None, None]:
60
+ linked = collect is not t3.collect and "t3" in cfg.agents and bool(cfg.t3_activity_since)
61
+ read_at = datetime.now(timezone.utc)
62
+ bindings = t3.native_bindings(cfg) if linked else {}
63
+ clients = t3.native_clients(cfg) if linked and collect is codex.collect else set()
64
+ with file_snapshot(snapshot):
65
+ source = collect(cfg, wm)
66
+ try:
67
+ while True:
68
+ try:
69
+ with file_snapshot(snapshot):
70
+ events, advance_watermark = next(source)
71
+ except StopIteration:
72
+ return
73
+ # A long native scan can reach app runs that started after its first snapshot.
74
+ if linked and any(stamp and stamp.tzinfo and stamp >= read_at
75
+ for event in events if (stamp := parse_ts(event.ts))):
76
+ read_at = datetime.now(timezone.utc)
77
+ bindings = t3.native_bindings(cfg)
78
+ if collect is codex.collect:
79
+ clients = t3.native_clients(cfg)
80
+ if bindings or clients:
81
+ events = t3.canonicalize(list(events), bindings, clients,
82
+ parse_ts(cfg.t3_activity_since))
83
+ for e in events:
84
+ e.machine = cfg.machine
85
+ yield events, advance_watermark
86
+ finally:
87
+ with file_snapshot(snapshot):
88
+ if close := getattr(source, "close", None):
89
+ close()
90
+
91
+
92
+ def drain(collect: Collect, cfg: Config, wm: dict[str, Any], name: str) -> Iterator[Iterator[Batch]]:
93
+ """One iterator of batches per pass of collect() over wm, each row stamped with this machine,
94
+ until a pass leaves wm unchanged. Native JSONL files stop at their first observed lengths;
95
+ later files and writes wait until the next run. Full-scan collectors never mutate wm, so
96
+ they settle after one pass. The consumer applies a pass's advances before asking for the next;
97
+ what it does with a row (validate, dedup, send) is its own."""
98
+ snapshot = FileSnapshot()
99
+ for _ in range(MAX_DRAIN_PASSES):
100
+ before = json.dumps(wm, sort_keys=True, default=str)
101
+ batches = _stamped(collect, cfg, wm, snapshot)
102
+ try:
103
+ yield batches
104
+ finally:
105
+ batches.close()
106
+ snapshot.restart_deferred()
107
+ snapshot.frozen = True
108
+ if json.dumps(wm, sort_keys=True, default=str) == before:
109
+ return
110
+ print(f"aut: warning: {name} hit the drain-pass cap ({MAX_DRAIN_PASSES}), so more rows remain "
111
+ "unread: a scan continues from here next run; export and backfill would restart.",
112
+ file=sys.stderr)
113
+
114
+
115
+ __all__ = ["REGISTRY", "Collect", "Collector", "drain"]