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,145 @@
1
+ """`aut label teach --task T --n N`: teacher (silver) labels for a stratified sample of units.
2
+
3
+ Every unit gets the local model's raw distribution. Units whose text comes from Claude Code logs
4
+ also get Claude Sonnet's, through the local `claude -p` CLI: that text already lives with
5
+ Anthropic, and nothing else is ever sent (plan: "Sonnet inputs are built only from Claude Code
6
+ fields"). Rows go to <task>.silver.jsonl, one per unit and teacher, appended as they come, so an
7
+ interrupted run resumes where it stopped. Sonnet spend is capped per run.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import re
14
+ import shutil
15
+ import subprocess # nosec B404 # one fixed argv in ask_claude, no shell
16
+ import tempfile
17
+ from collections import Counter
18
+ from dataclasses import dataclass
19
+ from datetime import datetime, timezone
20
+
21
+ from ..config import LABEL_DAYS, AutError, Config
22
+ from .backends import make_backend
23
+ from .core import Choice, Request, render_prompt
24
+ from .evalset import append_jsonl, eval_path, read_jsonl, stratified, unit_day, window_units
25
+ from .tasks import TASKS, Source
26
+
27
+ SONNET = "claude-sonnet-5-5"
28
+ _MILLI_PER_USD = 1000
29
+ # tasks.Source.texts reads Claude Code logs only, so these units carry Claude Code text (and
30
+ # counts) and nothing else. Window units (aw_block, aw_title) hold ActivityWatch titles: never sent.
31
+ CLAUDE_UNITS = frozenset({"steer", "episode_day", "episode"})
32
+ SYSTEM = ("You label one unit of a developer's own work for a private classifier. Read the facts, "
33
+ "weigh every option, and reply with the JSON object only.")
34
+ # Headless, no tools, no saved session (aut would read it back as a steer), no user settings or
35
+ # hooks, no MCP servers, no skills; run from an empty directory so no project CLAUDE.md loads.
36
+ CLAUDE_ARGS = ("-p", "--model", SONNET, "--output-format", "json", "--tools", "",
37
+ "--no-session-persistence", "--setting-sources", "project", "--strict-mcp-config",
38
+ "--disable-slash-commands", "--system-prompt", SYSTEM)
39
+ MAX_FAILS = 3 # consecutive claude failures (logged out, offline) end Sonnet's part
40
+
41
+
42
+ def sonnet_prompt(req: Request) -> str:
43
+ ids = [c["id"] for c in req.candidates]
44
+ body = render_prompt(req, ids).rsplit("\n\n", 1)[0] # drop the one-letter instruction
45
+ return (f"{body}\n\nReply with only a JSON object that maps each option name "
46
+ f"({', '.join(ids)}) to the probability that it is the answer; they sum to 1.")
47
+
48
+
49
+ def parse_dist(text: str, ids: list[str]) -> dict[str, float] | None:
50
+ m = re.search(r"\{.*\}", text or "", re.S)
51
+ try:
52
+ obj = json.loads(m.group(0)) if m else None
53
+ if not isinstance(obj, dict):
54
+ return None
55
+ vals = {i: max(float(obj.get(i) or 0), 0.0) for i in ids}
56
+ except (ValueError, TypeError):
57
+ return None
58
+ s = sum(vals.values())
59
+ return {i: v / s for i, v in vals.items()} if s > 0 else None
60
+
61
+
62
+ def ask_claude(prompt: str, timeout: int = 180) -> tuple[str, float]:
63
+ """(answer text, cost in USD) of one headless Sonnet call. Raises on any failure; the error
64
+ never carries the prompt or claude's output."""
65
+ exe = shutil.which("claude")
66
+ if not exe:
67
+ raise AutError("label teach: the claude CLI is not on PATH")
68
+ with tempfile.TemporaryDirectory() as d:
69
+ p = subprocess.run( # nosec B603 # constant args, no shell; the prompt goes over stdin
70
+ [exe, *CLAUDE_ARGS], input=prompt, capture_output=True, text=True,
71
+ encoding="utf-8", timeout=timeout, cwd=d)
72
+ if p.returncode:
73
+ raise RuntimeError(f"claude exited {p.returncode}")
74
+ o = json.loads(p.stdout)
75
+ if not isinstance(o, dict) or o.get("is_error"):
76
+ raise RuntimeError("claude returned an error")
77
+ return str(o.get("result") or ""), float(o.get("total_cost_usd") or 0)
78
+
79
+
80
+ @dataclass(slots=True)
81
+ class _SonnetRun:
82
+ """What ends Sonnet's part of a run: its spend and its consecutive failures."""
83
+ budget_usd: float
84
+ spent: float = 0.0
85
+ fails: int = 0
86
+
87
+
88
+ def _sonnet_dist(r: Request, run: _SonnetRun, c: Counter[str]) -> dict[str, float] | None:
89
+ """Sonnet's distribution for a unit; None (counted why) when there is none."""
90
+ if run.spent >= run.budget_usd or run.fails >= MAX_FAILS:
91
+ c["sonnet_skipped"] += 1
92
+ return None
93
+ try:
94
+ text, cost = ask_claude(sonnet_prompt(r))
95
+ except (RuntimeError, ValueError, OSError, subprocess.TimeoutExpired):
96
+ run.fails += 1
97
+ c["sonnet_failed"] += 1
98
+ return None
99
+ run.fails, run.spent = 0, run.spent + cost
100
+ dist = parse_dist(text, [x["id"] for x in r.candidates])
101
+ if dist is None:
102
+ c["sonnet_unusable"] += 1
103
+ return dist
104
+
105
+
106
+ def run_teach(cfg: Config, task: str, n: int, *, budget_usd: float = 5.0, days: int = LABEL_DAYS,
107
+ src: Source | None = None, now: datetime | None = None,
108
+ sonnet_only: bool = False) -> Counter[str]:
109
+ """Silver labels for up to n units not yet labelled by every teacher that applies to them. The
110
+ local teacher is the config's label_model, uncalibrated; sonnet_only skips it, and with it every
111
+ unit Sonnet may not read."""
112
+ t = TASKS[task]
113
+ today = (now or datetime.now(timezone.utc)).astimezone().date()
114
+ reqs = window_units(cfg, task, days, src, today)
115
+ local = None if sonnet_only else make_backend(task, Choice(), cfg.label_model,
116
+ cfg.label_llama_server)
117
+ out = eval_path(task, "silver")
118
+ have = {(r.get("unit_id"), r.get("teacher")) for r in read_jsonl(out)
119
+ if r.get("task_ver") == t.ver}
120
+
121
+ def wants(r: Request) -> list[str]:
122
+ teachers = ([local.model_id] if local else []) + ([SONNET] if r.unit in CLAUDE_UNITS else [])
123
+ return [x for x in teachers if (r.unit_id, x) not in have]
124
+
125
+ order = stratified(list(reqs.values()), lambda r: (r.unit, unit_day(r)), seed=task)
126
+ todo = [r for r in order if wants(r)][:n]
127
+ c: Counter[str] = Counter(units=len(todo))
128
+ sonnet, today_s = _SonnetRun(budget_usd), today.isoformat()
129
+ for r in todo:
130
+ for teacher in wants(r):
131
+ dist = _sonnet_dist(r, sonnet, c) if teacher == SONNET or local is None else local.distribution(r)
132
+ if dist is None:
133
+ continue
134
+ append_jsonl(out, {"unit_id": r.unit_id, "teacher": teacher, "task_ver": t.ver,
135
+ "date": today_s, "dist": {k: round(v, 4) for k, v in dist.items()}})
136
+ c["sonnet" if teacher == SONNET else "local"] += 1
137
+ c["spent_usd_milli"] = round(sonnet.spent * _MILLI_PER_USD)
138
+ return c
139
+
140
+
141
+ def print_teach(task: str, c: Counter[str], budget_usd: float) -> None:
142
+ print(f"label teach {task}: {c['units']} units, local {c['local']}, sonnet {c['sonnet']} "
143
+ f"(unusable {c['sonnet_unusable']}, failed {c['sonnet_failed']}, skipped "
144
+ f"{c['sonnet_skipped']}), spent ${c['spent_usd_milli'] / _MILLI_PER_USD:.2f} of "
145
+ f"${budget_usd:.2f} -> {eval_path(task, 'silver')}")
@@ -0,0 +1,128 @@
1
+ """The local pages' one server: 127.0.0.1, a random port, everything under a random token.
2
+
3
+ `aut episodes review`, `aut inspect` and `aut label review` keep their routes and forms; the bind,
4
+ the token gate, the body cap and the shutdown live here so they cannot drift apart.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import html
10
+ import secrets
11
+ import socket
12
+ import sys
13
+ import threading
14
+ import time
15
+ import webbrowser
16
+ from email.message import Message
17
+ from http.server import BaseHTTPRequestHandler, HTTPServer
18
+ from typing import Callable
19
+ from urllib.parse import parse_qs
20
+
21
+ from .push import redacted_error
22
+
23
+ _MAX_BODY = 1 << 20
24
+ _CSS = """:root { color-scheme: light dark; --bg: #fafafa; --fg: #1a1a1a; --mut: #666;
25
+ --line: #ddd; --acc: #2b5fd9; }
26
+ @media (prefers-color-scheme: dark) { :root { --bg: #161616; --fg: #eee; --mut: #aaa;
27
+ --line: #333; --acc: #7aa2ff; } }
28
+ body { background: var(--bg); color: var(--fg); font: 15px/1.45 system-ui, sans-serif;
29
+ margin: 0 auto; padding: 1rem; }
30
+ """
31
+
32
+
33
+ def head(title: str, max_width: str, css: str) -> str:
34
+ """A page's opening up to and including <body>: the shared theme plus the page's own css."""
35
+ return ('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" '
36
+ f'content="width=device-width, initial-scale=1"><title>{html.escape(title)}</title>'
37
+ f"<style>{_CSS}body {{ max-width: {max_width}; }}\n{css}</style></head><body>")
38
+
39
+
40
+ def new_token() -> str:
41
+ return secrets.token_urlsafe(16)
42
+
43
+
44
+ def _body_length(headers: Message) -> int:
45
+ try:
46
+ return int(headers.get("Content-Length") or 0)
47
+ except ValueError:
48
+ return 0
49
+
50
+
51
+ def serve(token: str, on_get: Callable[[str], bytes | None],
52
+ on_post: Callable[[dict[str, list[str]]], bytes | None], notice: str, *,
53
+ open_browser: bool = True, on_ready: Callable[[str], None] | None = None) -> None:
54
+ """Serve until a post ends it or Ctrl-C. on_get gets what follows /<token> in the path (query
55
+ included) and returns the page, None for a 404; only an exact match of that tail may answer.
56
+ on_post gets a form posted to /<token> and returns the closing page, or None to send the browser
57
+ back to /<token>. notice: the terminal line with {url}, printed when opening a browser."""
58
+ root = f"/{token}"
59
+
60
+ class Handler(BaseHTTPRequestHandler):
61
+ def log_message(self, *a: object) -> None: # keep titles, paths and unit text out of it
62
+ pass
63
+
64
+ def _reply(self, code: int, body: bytes, location: str | None = None) -> None:
65
+ self.send_response(code)
66
+ if location:
67
+ self.send_header("Location", location)
68
+ self.send_header("Content-Type", "text/html; charset=utf-8")
69
+ self.send_header("Content-Length", str(len(body)))
70
+ self.send_header("Cache-Control", "no-store")
71
+ self.end_headers()
72
+ self.wfile.write(body)
73
+
74
+ def do_GET(self) -> None:
75
+ page = on_get(self.path[len(root):]) if self.path.startswith(root) else None
76
+ self._reply(200 if page is not None else 404, b"not found" if page is None else page)
77
+
78
+ def _close_rejected_post(self) -> None:
79
+ # Let the client receive the 404 before unread POST bytes can reset the connection.
80
+ deadline, left = time.monotonic() + 1, _MAX_BODY
81
+ try:
82
+ self.wfile.flush()
83
+ self.connection.shutdown(socket.SHUT_WR)
84
+ while left:
85
+ remaining = deadline - time.monotonic()
86
+ if remaining <= 0:
87
+ break
88
+ self.connection.settimeout(remaining)
89
+ data = self.connection.recv(min(left, 65536))
90
+ if not data:
91
+ break
92
+ left -= len(data)
93
+ except OSError:
94
+ pass # The client may already have closed or reset its connection.
95
+
96
+ def do_POST(self) -> None:
97
+ # The token gates form parsing and saves; rejected bodies are only discarded.
98
+ if self.path != root or not 0 < _body_length(self.headers) <= _MAX_BODY:
99
+ self._reply(404, b"not found")
100
+ self._close_rejected_post()
101
+ return
102
+ form = parse_qs(self.rfile.read(_body_length(self.headers)).decode("utf-8", "replace"))
103
+ try:
104
+ closing = on_post(form)
105
+ except Exception as exc: # the answers exist only in the tab: let it resubmit
106
+ print(f"aut: save failed: {redacted_error(exc)}", file=sys.stderr)
107
+ self._reply(500, b"<p>Nothing was saved (the reason is in the terminal). Go back "
108
+ b"and submit again; the page is still running.</p>")
109
+ return
110
+ if closing is None:
111
+ self._reply(303, b"", root) # post, redirect, get: reload is safe
112
+ else:
113
+ self._reply(200, closing)
114
+ threading.Thread(target=self.server.shutdown).start()
115
+
116
+ srv = HTTPServer(("127.0.0.1", 0), Handler)
117
+ url = f"http://127.0.0.1:{srv.server_address[1]}{root}"
118
+ if on_ready:
119
+ on_ready(url)
120
+ if open_browser:
121
+ print("aut: " + notice.format(url=url), file=sys.stderr)
122
+ webbrowser.open(url)
123
+ try:
124
+ srv.serve_forever()
125
+ except KeyboardInterrupt: # the documented way to stop without saving
126
+ pass
127
+ finally:
128
+ srv.server_close()
@@ -0,0 +1,69 @@
1
+ """`aut time add`: one manual active-time interval, with its print_* report."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime, timedelta, timezone
6
+ from typing import NamedTuple
7
+
8
+ from .config import AutError, Config
9
+ from .event import TimeInterval, make_event_id
10
+ from .push import insert_pg
11
+
12
+ _MAX_MANUAL = timedelta(hours=16)
13
+
14
+
15
+ def _parse_local_datetime(value: str) -> datetime:
16
+ """A datetime typed by the user; no zone means this machine's local time."""
17
+ try:
18
+ dt = datetime.fromisoformat(value)
19
+ except ValueError:
20
+ raise AutError(f"time add: not a date and time: {value!r} (use YYYY-MM-DD HH:MM)") \
21
+ from None
22
+ return dt if dt.tzinfo else dt.astimezone()
23
+
24
+
25
+ class ManualSpan(NamedTuple):
26
+ """The interval as typed: --start and --end, or --minutes ending at --at (default now)."""
27
+ start: str | None = None
28
+ end: str | None = None
29
+ minutes: int | None = None
30
+ at: str | None = None
31
+
32
+
33
+ def build_manual_interval(cfg: Config, span: ManualSpan, *, not_relevant: bool = False,
34
+ now: datetime | None = None) -> TimeInterval:
35
+ """One manual agents.time_interval row, or AutError with the reason it was refused."""
36
+ now = now or datetime.now(timezone.utc)
37
+ if span.minutes is not None:
38
+ if span.start or span.end:
39
+ raise AutError("time add: use --start/--end or --minutes, not both")
40
+ end_dt = _parse_local_datetime(span.at) if span.at else now
41
+ start_dt = end_dt - timedelta(minutes=span.minutes)
42
+ elif span.start and span.end and not span.at:
43
+ start_dt, end_dt = _parse_local_datetime(span.start), _parse_local_datetime(span.end)
44
+ else:
45
+ raise AutError("time add: give --start and --end, or --minutes [--at]")
46
+ if end_dt <= start_dt:
47
+ raise AutError("time add: the end must be after the start")
48
+ if end_dt - start_dt > _MAX_MANUAL:
49
+ raise AutError("time add: an interval can span at most 16 hours")
50
+ if end_dt > now: # hours not yet worked are not active time
51
+ raise AutError("time add: the end is in the future")
52
+ s_iso = start_dt.astimezone(timezone.utc).isoformat()
53
+ e_iso = end_dt.astimezone(timezone.utc).isoformat()
54
+ return TimeInterval(event_id=make_event_id("manual", cfg.machine, s_iso, e_iso), ts=s_iso,
55
+ end_ts=e_iso, source="manual", app=None, title=None, category=None,
56
+ work_relevant=not not_relevant, attrs={}, machine=cfg.machine)
57
+
58
+
59
+ def run_time_add(cfg: Config, span: ManualSpan, *, not_relevant: bool = False) -> TimeInterval:
60
+ row = build_manual_interval(cfg, span, not_relevant=not_relevant)
61
+ insert_pg(cfg.require_pg("time add"), [row])
62
+ return row
63
+
64
+
65
+ def print_time_add(row: TimeInterval) -> None:
66
+ s, e = (datetime.fromisoformat(x).astimezone() for x in (row.ts, row.end_ts))
67
+ mins = (e - s).total_seconds() / 60
68
+ print(f"added manual interval {s:%Y-%m-%d %H:%M} -> {e:%Y-%m-%d %H:%M} ({mins:.0f} min, "
69
+ f"{'relevant' if row.work_relevant else 'not relevant'})")
@@ -0,0 +1,23 @@
1
+ """What a failed urllib call can raise, and which hosts count as this machine. URLError and
2
+ HTTPError are OSErrors; a truncated body or a garbled status line (IncompleteRead, BadStatusLine)
3
+ is an HTTPException, which is not."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import http.client
8
+ import urllib.request
9
+ from email.message import Message
10
+ from typing import IO
11
+
12
+ HTTP_ERRORS = (OSError, http.client.HTTPException)
13
+ LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
14
+
15
+
16
+ class NoRedirect(urllib.request.HTTPRedirectHandler):
17
+ """For `build_opener`: a 3xx raises HTTPError instead of being followed. Following would turn a
18
+ POST into a GET that looks like success, and it would carry a Cookie header to wherever the
19
+ redirect points."""
20
+
21
+ def redirect_request(self, req: urllib.request.Request, fp: IO[bytes], code: int, msg: str,
22
+ headers: Message, newurl: str) -> None:
23
+ return None
@@ -0,0 +1,65 @@
1
+ """Explicit local import, reports and opt-in receiver commands."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from .config import AutError
11
+ from .observations import import_file
12
+ from .observation_report import build_report, public_draft, render_html
13
+ from .state import atomic_write_text
14
+
15
+
16
+ def register(subparsers: Any) -> None:
17
+ parser = subparsers.add_parser('observe', help='private external observations')
18
+ parser.set_defaults(observation_command=True)
19
+ parser.add_argument('--db', type=Path, default=Path.home() / '.config/aut/observations.sqlite3')
20
+ actions = parser.add_subparsers(dest='observe_cmd', required=True)
21
+ action = actions.add_parser('import')
22
+ action.add_argument('file', type=Path)
23
+ action.add_argument('--format', choices=['jsonl', 'otlp'], required=True)
24
+ action.add_argument('--source', required=True)
25
+ action.add_argument('--stream', required=True)
26
+ action.add_argument('--role', choices=['primary', 'crosscheck'], required=True)
27
+ for name in ('report', 'export-public'):
28
+ action = actions.add_parser(name)
29
+ action.add_argument('--out', type=Path, required=name == 'export-public')
30
+ action.add_argument('--improve-root', type=Path)
31
+ if name == 'report':
32
+ action.add_argument('--format', choices=['json', 'html'], default='json')
33
+ action = actions.add_parser('serve')
34
+ action.add_argument('--host', default='127.0.0.1')
35
+ action.add_argument('--port', type=int, default=8766)
36
+ action.add_argument('--token-env', default='AUT_OBSERVE_TOKEN')
37
+
38
+
39
+ def run(args: argparse.Namespace) -> Any:
40
+ try:
41
+ if args.observe_cmd == 'import':
42
+ return import_file(args.db, args.file, format=args.format, source=args.source,
43
+ stream=args.stream, role=args.role)
44
+ if args.observe_cmd == 'serve':
45
+ from .observation_server import make_server
46
+ server = make_server(args.db, os.environ.get(args.token_env, ''), host=args.host, port=args.port)
47
+ try:
48
+ server.serve_forever()
49
+ finally:
50
+ server.server_close()
51
+ return None
52
+ report = build_report(args.db, improve_root=args.improve_root)
53
+ public = args.observe_cmd == 'export-public'
54
+ value = public_draft(report) if public else report
55
+ text = render_html(value) if not public and args.format == 'html' else json.dumps(value, indent=2, sort_keys=True)
56
+ if args.out:
57
+ target = args.out.expanduser().resolve()
58
+ if any((p / '.git').exists() for p in (target.parent, *target.parents)):
59
+ raise ValueError('report output must be outside Git')
60
+ target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
61
+ atomic_write_text(target, text + '\n')
62
+ return {'out': str(target), 'publication_status': 'local_draft' if public else 'private'}
63
+ return value if args.format == 'json' else text
64
+ except (OSError, ValueError, TypeError) as exc:
65
+ raise AutError('observe: command failed: ' + str(exc)) from exc
@@ -0,0 +1,116 @@
1
+ """Private reports and a fixed aggregate-only local publication draft."""
2
+ from __future__ import annotations
3
+
4
+ from collections import Counter
5
+ from datetime import datetime, timezone
6
+ from html import escape
7
+ import json
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from .observations import COUNTS, records, timestamp
12
+
13
+
14
+ def build_report(db: Path, *, improve_root: Path | None = None,
15
+ now: str | None = None) -> dict[str, Any]:
16
+ clock = timestamp(now) if now else datetime.now(timezone.utc)
17
+ rows = records(db)
18
+ usage = [r.get('delta') or r for r in rows if r['additive']]
19
+ sums = {}
20
+ for key in COUNTS:
21
+ known = [r[key] for r in usage if r[key] is not None]
22
+ missing = len(usage) - len(known)
23
+ sums[key] = {'total': sum(known) if usage and not missing else None,
24
+ 'known_sum': sum(known) if known else None, 'unknown_count': missing}
25
+ quotas: dict[tuple[str, ...], dict[str, Any]] = {}
26
+ tools: dict[str, Any] = {}
27
+ for r in rows:
28
+ if r['kind'] == 'quota':
29
+ quota_key = tuple(r[k] for k in ('source', 'stream', 'scope', 'unit', 'period'))
30
+ if quota_key not in quotas or timestamp(r['timestamp']) > timestamp(quotas[quota_key]['timestamp']):
31
+ quotas[quota_key] = dict(r)
32
+ if r['kind'] == 'tool':
33
+ key = json.dumps([r['source'], r['stream'], r['role']], separators=(',', ':'))
34
+ group = tools.setdefault(key, {'source': r['source'], 'stream': r['stream'],
35
+ 'role': r['role'], 'ok': 0, 'error': 0, 'unknown': 0,
36
+ 'operation_time_ms_known_sum': None, 'duration_unknown_count': 0})
37
+ group[r['status']] += 1
38
+ if r.get('duration_ms') is None:
39
+ group['duration_unknown_count'] += 1
40
+ else:
41
+ group['operation_time_ms_known_sum'] = (group['operation_time_ms_known_sum'] or 0) + r['duration_ms']
42
+ for r in quotas.values():
43
+ r['freshness'] = ('unknown' if r['fresh_until'] is None else
44
+ 'current' if timestamp(r['fresh_until']) >= clock else 'stale')
45
+ studies = []
46
+ desktop = []
47
+ if improve_root is not None:
48
+ from .improve.store import Store
49
+ from .improve.studies import assess
50
+ store = Store(improve_root)
51
+ studies = [assess(store, key) for key in store.keys('studies')]
52
+ desktop = [store.get('desktop_imports', key) for key in store.keys('desktop_imports')]
53
+ return {'schema_version': 1, 'generated_at': clock.astimezone(timezone.utc).isoformat(),
54
+ 'data_through': max(timestamp(r['timestamp']) for r in rows).astimezone(timezone.utc).isoformat() if rows else None,
55
+ 'usage': sums, 'quotas': list(quotas.values()), 'tools': tools,
56
+ 'coverage': {'observations': len(rows), 'additive_usage': len(usage),
57
+ 'crosschecks': sum(r['role'] == 'crosscheck' for r in rows),
58
+ 'nonadditive_usage': sum(r['kind'] == 'usage' and not r['additive'] for r in rows),
59
+ 'reasons': dict(Counter(r['coverage'] for r in rows if 'coverage' in r)),
60
+ 'completeness': 'unknown'},
61
+ 'studies': studies, 'desktop_imports': desktop,
62
+ 'scope': 'Observed operations and bounded study evidence; no general productivity claim.'}
63
+
64
+
65
+ def public_draft(report: dict[str, Any]) -> dict[str, Any]:
66
+ # Fixed count projection never copies identifiers or arbitrary report attributes.
67
+ tools = [value for value in report['tools'].values() if value['role'] == 'primary']
68
+ groups = {name: [r for r in tools if (r['source'] == 'agent-desktop') ==
69
+ (name == 'desktop')] for name in ('desktop', 'other')}
70
+ return {'schema_version': 1, 'publication_status': 'local_draft',
71
+ 'generated_at': report['generated_at'], 'data_through': report['data_through'],
72
+ 'observed_tools': {name: {key: sum(r[key] for r in selected) if selected else None
73
+ for key in ('ok', 'error', 'unknown')}
74
+ for name, selected in groups.items()},
75
+ 'study_decisions': {key: sum(r['scoped_decision'] == key for r in report['studies'])
76
+ for key in ('supported', 'inconclusive', 'rejected')},
77
+ 'coverage': {'completeness': 'unknown',
78
+ 'observations': report['coverage']['observations']}}
79
+
80
+
81
+ def render_html(report: dict[str, Any]) -> str:
82
+ def table(rows: list[list[Any]], headings: list[str]) -> str:
83
+ def cells(values: list[Any], tag: str) -> str:
84
+ return ''.join('<' + tag + '>' + escape(
85
+ 'unavailable' if v is None else str(v)) + '</' + tag + '>' for v in values)
86
+ return ('<div class="scroll"><table><thead><tr>' + cells(headings, 'th') +
87
+ '</tr></thead><tbody>' + ''.join('<tr>' + cells(row, 'td') + '</tr>'
88
+ for row in rows) + '</tbody></table></div>')
89
+
90
+ body = '<h2>Usage</h2>' + table([[key, value['total'], value['known_sum'],
91
+ value['unknown_count']] for key, value in report.get('usage', {}).items()],
92
+ ['Component', 'Complete total', 'Known sum (lower bound)', 'Unknown records'])
93
+ body += '<h2>Quota</h2>' + table([[r.get(k) for k in (
94
+ 'source', 'stream', 'role', 'scope', 'remaining', 'limit', 'unit', 'period',
95
+ 'reset', 'fresh_until', 'freshness')] for r in report.get('quotas', [])],
96
+ ['Source', 'Stream', 'Role', 'Scope', 'Remaining', 'Limit', 'Unit', 'Period',
97
+ 'Reset', 'Fresh until', 'Freshness'])
98
+ body += '<h2>Observed tools</h2>' + table([[r['source'], r['stream'], r['role'], r['ok'], r['error'], r['unknown'],
99
+ r['operation_time_ms_known_sum'], r['duration_unknown_count']]
100
+ for key, r in report.get('tools', {}).items()],
101
+ ['Source', 'Stream', 'Role', 'OK', 'Error', 'Unknown', 'Known operation time (ms)', 'Unknown durations'])
102
+ body += '<h2>Study evidence</h2>' + table([[r['study_id'], r['scoped_decision'],
103
+ r['primary_metric'], json.dumps(r['observed_effects']), json.dumps(r['cost_inputs']),
104
+ json.dumps(r['observed_cost'])] for r in report.get('studies', [])],
105
+ ['Study', 'Scoped decision', 'Metric', 'Effects', 'Cost inputs', 'Observed cost'])
106
+ body += '<h2>Coverage</h2><pre>' + escape(json.dumps(report.get('coverage'), indent=2)) + '</pre>'
107
+ body += '<details><summary>Private report details</summary><pre>' + escape(
108
+ json.dumps(report, indent=2, sort_keys=True, ensure_ascii=False)) + '</pre></details>'
109
+ return ('<!doctype html><html lang="en"><meta charset="utf-8">'
110
+ '<meta name="viewport" content="width=device-width"><title>Private observations</title>'
111
+ '<style>body{font:1rem system-ui;margin:2rem;max-width:80rem}.scroll,pre{overflow:auto}'
112
+ 'td,th{padding:.5rem;text-align:left;border:1px solid #aaa}table{border-collapse:collapse}'
113
+ 'pre{padding:1rem;background:#eee}h1{font-size:1.5rem}</style><main>'
114
+ '<h1>Private observations</h1><p>Unavailable values are unknown. Known sums may be lower bounds. '
115
+ 'Operation time is not elapsed task time or human activity. Crosschecks remain separate. '
116
+ 'Study decisions apply only to bounded observations.</p>' + body + '</main></html>')
@@ -0,0 +1,110 @@
1
+ """Opt-in internal receiver. Put nonloopback binds behind authenticated TLS."""
2
+ from __future__ import annotations
3
+
4
+ import hmac
5
+ from http.server import BaseHTTPRequestHandler, HTTPServer
6
+ import json
7
+ import sqlite3
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from .observations import MAX_FILE_BYTES, ingest
12
+ from .observation_report import build_report
13
+
14
+
15
+ def receive(db: Path, value: Any) -> dict[str, Any]:
16
+ if not isinstance(value, dict) or set(value) not in (
17
+ {'format', 'source', 'stream', 'role', 'records'},
18
+ {'format', 'source', 'stream', 'role', 'payload'}):
19
+ raise ValueError('invalid envelope')
20
+ options = {key: value[key] for key in ('source', 'stream', 'role')}
21
+ if value['format'] == 'jsonl' and 'records' in value and isinstance(value['records'], list):
22
+ result = ingest(db, value['records'], **options)
23
+ elif value['format'] == 'otlp' and 'payload' in value:
24
+ from .telemetry import normalize_otlp
25
+ normalized, unsupported = normalize_otlp(value['payload'])
26
+ result = ingest(db, normalized, **options)
27
+ result['unsupported'] = unsupported
28
+ else:
29
+ raise ValueError('invalid format')
30
+ return result
31
+
32
+
33
+ def make_server(db: Path, token: str, *, host: str = '127.0.0.1', port: int = 8766) -> HTTPServer:
34
+ if not isinstance(token, str) or len(token) < 16 or any(c.isspace() for c in token):
35
+ raise ValueError('receiver token must contain at least 16 non-whitespace characters')
36
+
37
+ class Handler(BaseHTTPRequestHandler):
38
+ def setup(self) -> None:
39
+ super().setup()
40
+ self.connection.settimeout(5)
41
+
42
+ def log_message(self, format: str, *args: Any) -> None:
43
+ pass
44
+
45
+ def reply(self, status: int, value: Any) -> None:
46
+ body = json.dumps(value, allow_nan=False).encode()
47
+ self.send_response(status)
48
+ self.send_header('Content-Type', 'application/json')
49
+ self.send_header('Content-Length', str(len(body)))
50
+ self.send_header('Cache-Control', 'no-store')
51
+ self.end_headers()
52
+ self.wfile.write(body)
53
+
54
+ def authorized(self) -> bool:
55
+ values = self.headers.get_all('Authorization', [])
56
+ valid = len(values) == 1 and hmac.compare_digest(values[0].encode(), ('Bearer ' + token).encode())
57
+ if not valid:
58
+ self.reply(401, {'error': 'unauthorized'})
59
+ return valid
60
+
61
+ def do_GET(self) -> None:
62
+ if self.path == '/health':
63
+ self.reply(200, {'status': 'ok'})
64
+ elif self.path == '/v1/report':
65
+ if self.authorized():
66
+ try:
67
+ self.reply(200, build_report(db))
68
+ except (OSError, ValueError, sqlite3.Error):
69
+ self.reply(500, {'error': 'report unavailable'})
70
+ else:
71
+ self.reply(404, {'error': 'unknown route'})
72
+
73
+ def do_POST(self) -> None:
74
+ if self.path != '/v1/ingest':
75
+ self.reply(404, {'error': 'unknown route'})
76
+ return
77
+ if not self.authorized():
78
+ return
79
+ lengths = self.headers.get_all('Content-Length', [])
80
+ if self.headers.get_all('Transfer-Encoding') or len(lengths) != 1 or not lengths[0].isascii() or not lengths[0].isdigit():
81
+ self.reply(400, {'error': 'invalid framing'})
82
+ return
83
+ if self.headers.get_all('Content-Type') != ['application/json']:
84
+ self.reply(415, {'error': 'expected application/json'})
85
+ return
86
+ if len(lengths[0]) > 8:
87
+ self.reply(413, {'error': 'body too large'})
88
+ return
89
+ size = int(lengths[0])
90
+ if size > MAX_FILE_BYTES:
91
+ self.reply(413, {'error': 'body too large'})
92
+ return
93
+ try:
94
+ data = self.rfile.read(size)
95
+ if len(data) != size:
96
+ raise ValueError('incomplete body')
97
+ value = json.loads(data, parse_constant=lambda _: (_ for _ in ()).throw(ValueError()))
98
+ result = receive(db, value)
99
+ except (ValueError, TypeError, KeyError, UnicodeError, AttributeError, RecursionError):
100
+ self.reply(400, {'error': 'invalid observation batch'})
101
+ return
102
+ except (OSError, sqlite3.Error):
103
+ self.reply(503, {'error': 'storage unavailable'})
104
+ return
105
+ if result['conflicts']:
106
+ self.reply(409, {'error': 'conflicting evidence; other records may be durable', 'receipt': result})
107
+ else:
108
+ self.reply(200, result)
109
+
110
+ return HTTPServer((host, port), Handler)