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,121 @@
1
+ """Apply a frozen descriptive decision rule to paired stored observations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from typing import Any, cast
7
+
8
+ from pathlib import Path
9
+
10
+ from .store import Store, digest
11
+
12
+
13
+ def experiment_identity(store: Store, spec_id: str) -> str:
14
+ """Identify executed inputs; ignored notes and case names cannot create fresh work."""
15
+ spec = store.get("trial_specs", spec_id)
16
+ cases = [digest({name: case[name] for name in (
17
+ "argv", "timeout_s", "acceptance_argv", "acceptance_files") if name in case})
18
+ for case in spec["cases"]]
19
+ return digest({"kind": spec["kind"],
20
+ "directories": {name: str(Path(root).resolve())
21
+ for name, root in spec["directories"].items()},
22
+ "files": spec.get("files", {}), "cases": sorted(set(cases))})
23
+
24
+
25
+ def observed_experiment(store: Store, spec_id: str, *, allow_resume: bool = False) -> bool:
26
+ identity = experiment_identity(store, spec_id)
27
+ return any(experiment_identity(store, source) == identity
28
+ for key in store.keys("trial_results")
29
+ if (source := store.get("trial_results", key)["spec_id"]) != spec_id
30
+ or not allow_resume)
31
+
32
+
33
+ def measure(store: Store, spec_id: str, metric: str, policy: dict[str, Any],
34
+ proposal: dict[str, Any]) -> dict[str, Any]:
35
+ spec = store.get("trial_specs", spec_id)
36
+ expected = {(repeat, case["id"], condition) for repeat in range(spec["repeats"])
37
+ for case in spec["cases"] for condition in ("baseline", "candidate")}
38
+ rows = {}
39
+ duplicates = 0
40
+ for key in store.keys("trial_results"):
41
+ row = store.get("trial_results", key)
42
+ if row["spec_id"] == spec_id:
43
+ marker = (row["repeat"], row["case_id"], row["condition"])
44
+ duplicates += marker in rows
45
+ rows[marker] = row
46
+ values: dict[str, list[float]] = {"baseline": [], "candidate": []}
47
+ deltas = []
48
+ regressions = []
49
+ failures = []
50
+ missing = 0
51
+ missing_quality = 0
52
+ invalid = 0
53
+ for repeat in range(spec["repeats"]):
54
+ for case in spec["cases"]:
55
+ pair = {condition: rows.get((repeat, case["id"], condition))
56
+ for condition in ("baseline", "candidate")}
57
+ observed: dict[str, float] = {}
58
+ for condition, observation in pair.items():
59
+ if observation and observation.get("validation_error"):
60
+ invalid += 1
61
+ missing += 1
62
+ missing_quality += 1
63
+ continue
64
+ accepted = observation.get("accepted") if observation else None
65
+ missing_quality += type(accepted) is not bool
66
+ if condition == "candidate" and accepted is False:
67
+ failures.append({"repeat": repeat, "case_id": case["id"]})
68
+ value = ((int(accepted) if type(accepted) is bool else None)
69
+ if metric == "accepted" else observation.get("elapsed_s")
70
+ if metric == "elapsed_s" and observation else
71
+ (observation.get("metrics") or {}).get(metric) if observation else None)
72
+ if type(value) not in (int, float) or not math.isfinite(cast(float, value)) or cast(float, value) < 0:
73
+ missing += 1
74
+ else:
75
+ observed[condition] = cast(float, value)
76
+ values[condition].append(cast(float, value))
77
+ if pair["baseline"] and pair["candidate"] and not any(
78
+ row.get("validation_error") for row in pair.values() if row) \
79
+ and pair["baseline"].get("accepted") \
80
+ and pair["candidate"].get("accepted") is False:
81
+ regressions.append({"repeat": repeat, "case_id": case["id"]})
82
+ if set(observed) == {"baseline", "candidate"}:
83
+ deltas.append(observed["candidate"] - observed["baseline"])
84
+ protected = bool(all(spec.get("files", {}).get(condition, {}).get(proposal["target"])
85
+ == proposal[f"{name}_sha256"]
86
+ for condition, name in (("baseline", "before"), ("candidate", "after")))
87
+ and all(case.get("acceptance_files") for case in spec["cases"]))
88
+ delta = sum(deltas) / len(deltas) if deltas and not missing else None
89
+ improvement = (delta if policy["direction"] == "increase" else -delta) \
90
+ if delta is not None else None
91
+ complete = set(rows) == expected and not duplicates
92
+ decision = "inconclusive"
93
+ reasons = []
94
+ if not complete or missing or missing_quality:
95
+ reasons.append("Incomplete or ambiguous paired observations.")
96
+ if invalid:
97
+ reasons.append("Rejected execution receipts are excluded from measured support.")
98
+ if not protected:
99
+ reasons.append("Protected proposal fixtures and acceptance hashes are missing.")
100
+ quality_failed = ((policy["require_no_acceptance_regressions"] and bool(regressions)) or
101
+ (policy["require_all_candidate_accepted"] and bool(failures)))
102
+ if quality_failed and complete and not missing and not missing_quality:
103
+ decision = "rejected"
104
+ reasons.append("The prospective acceptance constraint failed.")
105
+ elif complete and not missing and not missing_quality and protected and improvement is not None:
106
+ if improvement > policy["minimum_improvement"]:
107
+ decision = "supported"
108
+ elif improvement < 0:
109
+ decision = "rejected"
110
+ reasons.append("The selected metric worsened.")
111
+ else:
112
+ reasons.append("The selected metric does not exceed the prospective improvement minimum.")
113
+ return {"decision": decision, "primary_metric": metric, "primary_metric_delta": delta,
114
+ "improvement": improvement, "pairs": len(deltas), "expected_pairs": len(expected) // 2,
115
+ "missing_observations": missing, "missing_quality": missing_quality,
116
+ "invalid_observations": invalid, "duplicate_observations": duplicates, "acceptance_regressions": regressions,
117
+ "candidate_failures": failures, "protected_inputs": protected,
118
+ "conditions": {name: sum(v) / len(v) if v else None for name, v in values.items()},
119
+ "reasons": reasons, "scope": "command/code correctness" if spec["kind"] == "command_check"
120
+ else "bounded agent-task benefit", "statistical_calibration": False,
121
+ "general_productivity_verified": False}
@@ -0,0 +1,174 @@
1
+ """Run fresh trusted agent tasks and retain only scoped, reviewed transfer summaries."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from ..config import AutError
10
+ from .proposals import file_digest
11
+ from .store import Store
12
+ from .studies import fields, identity, strings
13
+ from .study_decision import experiment_identity, observed_experiment
14
+ from .trial import _acceptance_inputs, _spec, run_trial
15
+
16
+
17
+ def followup(store: Store, study_id: str, spec: dict[str, Any], *,
18
+ execute: bool = False) -> dict[str, Any]:
19
+ study = store.get("studies", study_id)
20
+ try:
21
+ fields(spec, "version trial_spec_id evidence_cases task_families producer_id "
22
+ "project_scope provenance trial_case_evidence")
23
+ if spec["version"] != 1:
24
+ raise ValueError
25
+ strings(spec["evidence_cases"])
26
+ if not isinstance(spec["producer_id"], str) or not spec["producer_id"].strip():
27
+ raise ValueError
28
+ if not isinstance(spec["project_scope"], str) or not spec["project_scope"].strip():
29
+ raise ValueError
30
+ if set(spec["task_families"]) != set(spec["evidence_cases"]) or any(
31
+ not isinstance(v, str) or not v.strip() for v in spec["task_families"].values()):
32
+ raise ValueError
33
+ fields(spec["provenance"], "setup model tools instructions")
34
+ if any(v is not None and (not isinstance(v, str) or not v.strip())
35
+ for v in spec["provenance"].values()):
36
+ raise ValueError
37
+ trial = _spec(store, spec["trial_spec_id"])
38
+ mapping = spec["trial_case_evidence"]
39
+ if not isinstance(mapping, dict) or set(mapping) != {c["id"] for c in trial["cases"]}:
40
+ raise AutError("improve: trial evidence mapping must cover every executed case")
41
+ associated = set()
42
+ for linked in mapping.values():
43
+ strings(linked)
44
+ if not set(linked) <= set(spec["evidence_cases"]):
45
+ raise AutError("improve: trial evidence mapping cites unavailable evidence")
46
+ associated.update(linked)
47
+ if associated != set(spec["evidence_cases"]):
48
+ raise AutError("improve: trial evidence mapping must use every declared evidence case")
49
+ overlap = sorted(set(spec["task_families"].values()) & {
50
+ study["task_families"][key] for key in
51
+ study["discovery_cases"] + study["control_cases"]})
52
+ independence = {"declared_family_overlap": overlap, "verified": not overlap,
53
+ "association_authority": "operator_declared_case_mapping",
54
+ "trial_case_evidence": mapping,
55
+ "scope": "Declared grouping and association only; no independent provenance attestation."}
56
+ if trial["kind"] == "command_check":
57
+ for case in trial["cases"]:
58
+ if not case.get("acceptance_files"):
59
+ raise AutError("improve: follow-up requires protected command acceptance")
60
+ protected = {"acceptance_argv": case["argv"],
61
+ "acceptance_files": case["acceptance_files"]}
62
+ roots = [Path(root).resolve() for root in trial["directories"].values()]
63
+ for root in roots:
64
+ _acceptance_inputs(protected, roots, root)
65
+ old_cases = list(study["discovery_cases"] + study["control_cases"])
66
+ for key in store.keys("study_followups"):
67
+ prior = store.get("study_followups", key)
68
+ if prior["study_id"] == study_id and prior["spec"] != spec:
69
+ old_cases.extend(prior["spec"]["evidence_cases"])
70
+ old = [identity(store, key) for key in old_cases]
71
+ old_events = {(identity(store, key)["session"], event["id"])
72
+ for key in old_cases for event in store.get("cases", key)["events"]}
73
+ fresh_events = {(identity(store, key)["session"], event["id"])
74
+ for key in spec["evidence_cases"]
75
+ for event in store.get("cases", key)["events"]}
76
+ if old_events & fresh_events:
77
+ raise AutError("improve: follow-up reuses prior source event identities")
78
+ fresh = [identity(store, key) for key in spec["evidence_cases"]]
79
+ if len({row["content"] for row in fresh}) != len(fresh) or any(
80
+ row["content"] == prior["content"]
81
+ for row in fresh for prior in old):
82
+ raise AutError("improve: follow-up evidence must be fresh, not copied discovery")
83
+ observed_times = [event.get("timestamp") for key in spec["evidence_cases"]
84
+ for event in store.get("cases", key)["events"]]
85
+ temporal_verified = bool(observed_times)
86
+ for stamp in observed_times:
87
+ try:
88
+ temporal_verified = temporal_verified and isinstance(stamp, str) and (
89
+ datetime.fromisoformat(stamp) > datetime.fromisoformat(study["created_at"]))
90
+ except (ValueError, TypeError):
91
+ temporal_verified = False
92
+ freshness = {"observed_event_times": observed_times,
93
+ "policy_created_at": study["created_at"],
94
+ "work_after_policy_verified": temporal_verified,
95
+ "source_event_overlap": False,
96
+ "scope": "Observed timestamps only; participant and loaded instruction exposure unknown."}
97
+ proposal = store.get("proposals", study["proposal_id"])
98
+ relative = proposal["target"]
99
+ for condition, expected in (("baseline", proposal["before_sha256"]),
100
+ ("candidate", proposal["after_sha256"])):
101
+ path = Path(trial["directories"][condition]) / relative
102
+ if trial["files"][condition].get(relative) != expected or file_digest(path) != expected:
103
+ raise AutError("improve: follow-up candidate exposure is not hash-pinned")
104
+ if experiment_identity(store, spec["trial_spec_id"]) == experiment_identity(
105
+ store, study["trial_spec_id"]):
106
+ raise AutError("improve: follow-up requires a fresh trial specification")
107
+ resume = any(store.get("study_followup_specs", saved) ==
108
+ {"study_id": study_id, "spec": spec}
109
+ for saved in store.keys("study_followup_specs"))
110
+ if observed_experiment(store, spec["trial_spec_id"], allow_resume=resume):
111
+ raise AutError("improve: follow-up cannot reuse prior trial results")
112
+ except (KeyError, TypeError, ValueError, OSError, AttributeError) as exc:
113
+ raise AutError("improve: invalid follow-up specification") from exc
114
+ if not execute:
115
+ return {"study_id": study_id, "execution_required": True,
116
+ "trial_spec_id": spec["trial_spec_id"], "evidence_cases": spec["evidence_cases"],
117
+ "candidate_exposure": "protected fixture hashes", "freshness": freshness,
118
+ "independence": independence, "executed": 0}
119
+ store.put("study_followup_specs", {"study_id": study_id, "spec": spec})
120
+ result = run_trial(store, spec["trial_spec_id"], execute=True, budget_s=study["budget_s"])
121
+ if trial["kind"] == "command_check":
122
+ for case in trial["cases"]:
123
+ protected = {"acceptance_argv": case["argv"],
124
+ "acceptance_files": case["acceptance_files"]}
125
+ for root in roots:
126
+ _acceptance_inputs(protected, roots, root)
127
+ record = {"study_id": study_id, "spec": spec, "trial": result, "freshness": freshness,
128
+ "independence": independence,
129
+ "scope": "command/code correctness" if trial["kind"] == "command_check"
130
+ else "bounded agent-task observations",
131
+ "general_productivity_verified": False}
132
+ key = store.put("study_followups", record)
133
+ store.append("study_followup", study_id=study_id, followup_id=key)
134
+ return {"followup_id": key, **record}
135
+
136
+
137
+ def transfer(store: Store, study_id: str, spec: dict[str, Any]) -> dict[str, Any]:
138
+ study = store.get("studies", study_id)
139
+ try:
140
+ fields(spec, "version participant_id producer_id project_scope consent "
141
+ "outcome_ids reviewed_outcome_ids")
142
+ fields(spec["consent"], "participant_id project_scope status")
143
+ if spec["version"] != 1 or any(not isinstance(spec[k], str) or not spec[k].strip()
144
+ for k in ("participant_id", "producer_id", "project_scope")):
145
+ raise ValueError
146
+ consent = spec["consent"]
147
+ if consent != {"participant_id": spec["participant_id"],
148
+ "project_scope": spec["project_scope"], "status": "granted"}:
149
+ raise AutError("improve: participant consent is absent, revoked or out of scope")
150
+ strings(spec["outcome_ids"])
151
+ strings(spec["reviewed_outcome_ids"])
152
+ if set(spec["outcome_ids"]) != set(spec["reviewed_outcome_ids"]):
153
+ raise AutError("improve: only explicitly reviewed outcomes can transfer")
154
+ findings = []
155
+ for key in spec["outcome_ids"]:
156
+ outcome = store.get("study_followups", key)
157
+ source = outcome["spec"]
158
+ if outcome["study_id"] != study_id or source["producer_id"] == spec["producer_id"] \
159
+ or source["project_scope"] != spec["project_scope"]:
160
+ raise AutError("improve: transfer needs distinct producer and matching project scope")
161
+ if set(source["evidence_cases"]) & set(study["discovery_cases"] + study["control_cases"]):
162
+ raise AutError("improve: transfer outcome reuses discovery")
163
+ findings.append({"outcome_id": key, "finished": outcome["trial"]["finished"],
164
+ "total": outcome["trial"]["total"], "accepted": outcome["trial"]["accepted"],
165
+ "complete": outcome["trial"]["complete"]})
166
+ except (KeyError, TypeError, ValueError, AttributeError) as exc:
167
+ raise AutError("improve: invalid participant transfer specification") from exc
168
+ record = {"study_id": study_id, "participant_id": spec["participant_id"],
169
+ "producer_id": spec["producer_id"], "project_scope": spec["project_scope"],
170
+ "consent": consent, "findings": findings, "actual_participant_pilot_verified": False,
171
+ "scope": "Reviewed stored outcomes only; participant identity and independence unverified."}
172
+ key = store.put("study_transfers", record)
173
+ store.append("study_transfer", study_id=study_id, transfer_id=key)
174
+ return {"transfer_id": key, **record}
@@ -0,0 +1,269 @@
1
+ """Read T3's local projections in one read-only SQLite snapshot."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import sqlite3
8
+ import time
9
+ from collections import Counter
10
+ from contextlib import closing
11
+ from datetime import datetime, timezone
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from ..collectors.activity_common import result_status
16
+ from ..event import parse_ts
17
+ from ..redact import redact
18
+ from .evidence import TEXT_LIMIT, VERSION, _text
19
+
20
+ MAX_ROWS = 20000
21
+ HUMAN_SOURCES = {"web", "mobile"}
22
+ # Item states after which T3 will add no output.
23
+ TERMINAL = {"completed", "failed", "error", "interrupted", "cancelled"}
24
+
25
+
26
+ def _hash(value: Any) -> str:
27
+ return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
28
+
29
+
30
+ def snapshots(home: Path, *, since: float, limit: int, idle_s: int,
31
+ max_bytes: int) -> tuple[list[dict[str, Any]], Counter[str]]:
32
+ path = home / ".t3/userdata/statev2.sqlite"
33
+ counts: Counter[str] = Counter()
34
+ if not path.exists():
35
+ return [], counts
36
+ rows: list[dict[str, Any]] = []
37
+ cutoff = datetime.fromtimestamp(since, timezone.utc).isoformat()
38
+ try:
39
+ with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True, timeout=1)) as db:
40
+ db.execute("PRAGMA query_only=ON")
41
+ db.execute("BEGIN")
42
+ threads = db.execute("""SELECT t.thread_id, t.updated_at,
43
+ CASE WHEN length(CAST(t.payload_json AS BLOB))<=? THEN t.payload_json END,
44
+ p.workspace_root FROM orchestration_v2_projection_threads t
45
+ LEFT JOIN projection_projects p ON p.project_id=t.project_id
46
+ WHERE julianday(t.updated_at)>=julianday(?)
47
+ ORDER BY EXISTS(SELECT 1 FROM orchestration_v2_projection_messages m
48
+ WHERE m.thread_id=t.thread_id AND m.role='user'
49
+ AND json_extract(m.payload_json,'$.createdBy')='user') DESC,
50
+ t.updated_at DESC, t.thread_id LIMIT ?""", (max_bytes, cutoff, limit + 1))
51
+ for index, (thread, updated, payload, cwd) in enumerate(threads):
52
+ if index >= limit:
53
+ counts['t3_unread_threads'] += 1
54
+ break
55
+ if payload is None:
56
+ counts['t3_byte_capped_threads'] += 1
57
+ continue
58
+ stamp = parse_ts(updated)
59
+ if not stamp or not stamp.tzinfo:
60
+ counts['t3_invalid_threads'] += 1
61
+ continue
62
+ if stamp.timestamp() > time.time() - idle_s:
63
+ counts['t3_active_threads'] += 1
64
+ continue
65
+ meta = json.loads(payload)
66
+ if not isinstance(meta, dict):
67
+ raise ValueError('invalid thread metadata')
68
+ metadata_bytes = len(payload.encode())
69
+ result = _thread(db, path, thread, meta.get('worktreePath') or cwd or '',
70
+ since, max_bytes - metadata_bytes, counts)
71
+ if result:
72
+ result['source']['bytes'] += metadata_bytes
73
+ result['source']['metadata_sha256'] = _hash(meta)
74
+ rows.append(result)
75
+ except (sqlite3.Error, OSError, ValueError, TypeError, OverflowError):
76
+ counts['t3_unreadable_sources'] += 1
77
+ return rows, counts
78
+
79
+
80
+ def _thread(db: sqlite3.Connection, path: Path, thread: str, cwd: str, since: float,
81
+ max_bytes: int, totals: Counter[str]) -> dict[str, Any] | None:
82
+ coverage: Counter[str] = Counter()
83
+ captured: list[dict[str, Any]] = []
84
+ events: list[dict[str, Any]] = []
85
+ used = 0
86
+
87
+ cutoff = datetime.fromtimestamp(since, timezone.utc).isoformat()
88
+
89
+ def records(table: str, columns: str, order: str, where: str = '',
90
+ params: tuple[Any, ...] = ()) -> list[dict[str, Any]]:
91
+ nonlocal used
92
+ # Table and column names are internal constants; record bodies share one byte budget.
93
+ rows = db.execute(f'SELECT {columns},substr(payload_json,1,?) FROM {table} '
94
+ f'WHERE thread_id=? {where} ORDER BY {order} LIMIT ?',
95
+ (max_bytes + 1, thread, *params, MAX_ROWS + 1))
96
+ result = []
97
+ for index, row in enumerate(rows):
98
+ raw = row[-1]
99
+ if index >= MAX_ROWS or used + len(raw.encode()) > max_bytes:
100
+ coverage['byte_cap_reached'] = 1
101
+ break
102
+ used += len(raw.encode())
103
+ value = json.loads(raw)
104
+ if not isinstance(value, dict):
105
+ raise ValueError('invalid projection record')
106
+ record = {'table': table, 'key': row[0], 'columns': list(row[:-1]), 'value': value}
107
+ captured.append(record)
108
+ result.append(record)
109
+ return result
110
+
111
+ recent = ('SELECT run_id FROM orchestration_v2_projection_runs '
112
+ 'WHERE thread_id=? AND julianday(requested_at)>=julianday(?)')
113
+ recent_providers = recent.replace('SELECT run_id', 'SELECT provider_thread_id')
114
+ proven_human = ("EXISTS(SELECT 1 FROM orchestration_v2_projection_messages m "
115
+ "WHERE m.message_id=json_extract(orchestration_v2_projection_runs.payload_json,"
116
+ "'$.userMessageId') AND m.run_id=orchestration_v2_projection_runs.run_id "
117
+ "AND m.role='user' AND json_extract(m.payload_json,'$.createdBy')='user' "
118
+ "AND json_extract(m.payload_json,'$.creationSource') IN ('web','mobile'))")
119
+ runs = records('orchestration_v2_projection_runs',
120
+ 'run_id,provider,provider_thread_id,status,requested_at,completed_at,'
121
+ + proven_human, 'ordinal,run_id',
122
+ 'AND julianday(requested_at)>=julianday(?)', (cutoff,))
123
+ messages = records('orchestration_v2_projection_messages',
124
+ 'message_id,run_id,role,created_at', 'created_at,message_id',
125
+ f'AND run_id IN ({recent}) AND role=\'user\' '
126
+ "AND json_extract(payload_json,'$.createdBy')='user' "
127
+ "AND json_extract(payload_json,'$.creationSource') IN ('web','mobile')",
128
+ (thread, cutoff))
129
+ providers = records('orchestration_v2_projection_provider_threads',
130
+ 'provider_thread_id,provider', 'provider_thread_id',
131
+ f'AND provider_thread_id IN ({recent_providers})', (thread, cutoff))
132
+ items = records('orchestration_v2_projection_turn_items',
133
+ 'turn_item_id,run_id,type,status,updated_at', 'updated_at DESC,ordinal DESC',
134
+ f'AND run_id IN ({recent}) AND type<>\'reasoning\'', (thread, cutoff))
135
+ provider_map = {r['key']: r['value'] for r in providers}
136
+ human = {r['key']: r for r in messages if r['columns'][2] == 'user'
137
+ and r['value'].get('createdBy') == 'user'
138
+ and r['value'].get('creationSource') in HUMAN_SOURCES}
139
+ native: set[tuple[str, str]] = set()
140
+ seen_providers: set[str] = set()
141
+ run_coverage: dict[str, dict[str, Any]] = {}
142
+
143
+ def emit(kind: str, value: Any, record: dict[str, Any], timestamp: Any,
144
+ run: str, provider: str, *, call: str = '', tool: str = '',
145
+ status: str = 'unknown') -> None:
146
+ stamp = parse_ts(timestamp)
147
+ if not stamp or not stamp.tzinfo:
148
+ coverage['missing_timestamps'] += 1
149
+ return
150
+ raw = _text(value)
151
+ text = redact(raw)
152
+ clipped = len(text) > TEXT_LIMIT
153
+ coverage['truncated_events'] += clipped
154
+ events.append({'id': _hash([thread, run, record['key'], kind])[:32],
155
+ 'kind': kind, 'line': None, 'byte_offset': None,
156
+ 'record_id': record['key'], 'table': record['table'],
157
+ 'timestamp': stamp.isoformat(), 'text': text[:TEXT_LIMIT],
158
+ 'truncated': clipped, 'source_sha256': _hash(raw),
159
+ 'call_id': call, 'tool': tool, 'status': status,
160
+ 'run_id': run, 'provider': provider})
161
+
162
+ for run in runs:
163
+ before = coverage.copy()
164
+ key, provider, provider_thread, status, requested, completed, proven = run['columns']
165
+ prompt = human.get(run['value'].get('userMessageId'))
166
+ if not proven:
167
+ totals['t3_automated_runs'] += 1
168
+ continue
169
+ if not prompt or prompt['columns'][1] != key:
170
+ totals['t3_uncaptured_runs'] += 1
171
+ continue
172
+ stamp = parse_ts(requested)
173
+ if not stamp or not stamp.tzinfo:
174
+ coverage['missing_timestamps'] += 1
175
+ continue
176
+ if stamp.timestamp() < since:
177
+ continue
178
+ seen_providers.add(provider)
179
+ ref = provider_map.get(provider_thread, {}).get('nativeThreadRef') or {}
180
+ if not isinstance(ref, dict):
181
+ ref = {}
182
+ if ref.get('strength') == 'strong' and isinstance(ref.get('nativeId'), str):
183
+ agent = {'codex': 'codex', 'claudeAgent': 'claude_code'}.get(str(ref.get('driver')))
184
+ if agent:
185
+ native.add((agent, ref['nativeId']))
186
+ for message in human.values():
187
+ if message['columns'][1] == key:
188
+ emit('prompt', message['value'].get('text', ''), message,
189
+ message['columns'][3], key, provider)
190
+ if message['value'].get('attachments') or message['value'].get('context'):
191
+ coverage['projection_gaps'] += 1
192
+ run_items = [item for item in items if item['columns'][1] == key]
193
+ if not run_items:
194
+ coverage['projection_gaps'] += 1
195
+ for item in run_items:
196
+ value = item['value']
197
+ kind = value.get('type')
198
+ at = value.get('startedAt') or item['columns'][4]
199
+ end = value.get('completedAt') or item['columns'][4]
200
+ if kind in {'command_execution', 'dynamic_tool', 'file_change', 'error'}:
201
+ name = value.get('toolName') or str(kind)
202
+ call_id = str(item['key'])
203
+ body = ({'file': value.get('fileName'), 'diff': value.get('diffStr')}
204
+ if kind == 'file_change' else value.get('input', ''))
205
+ emit('call', body, item, at, key, provider, call=call_id, tool=name)
206
+ item_state = value.get('status')
207
+ if kind in {'file_change', 'error'} or 'output' in value or item_state in TERMINAL:
208
+ # T3 omits the output key when a finished command printed nothing.
209
+ output = (value.get('failure') if kind == 'error' else
210
+ 'File change reported ' + str(item_state)
211
+ if kind == 'file_change' else value.get('output', ''))
212
+ failed = item_state in {'failed', 'error'}
213
+ if isinstance(output, dict):
214
+ failed = failed or output.get('isError') is True
215
+ if kind in {'file_change', 'error'} or 'output' in value:
216
+ result = result_status(_text(output), failed)
217
+ elif type(value.get('exitCode')) is int:
218
+ result = result_status({'exit_code': value['exitCode']}, failed)
219
+ else:
220
+ result = ('error' if failed else
221
+ 'success' if item_state == 'completed' else 'unknown')
222
+ emit('result', output, item, end, key, provider, call=call_id,
223
+ status=result)
224
+ elif kind == 'assistant_message':
225
+ emit('reply', value.get('text', ''), item, end, key, provider)
226
+ if value.get('streaming'):
227
+ coverage['projection_gaps'] += 1
228
+ elif kind in {'compaction', 'handoff'}:
229
+ emit('compaction', 'Context changed: ' + kind, item, at, key, provider)
230
+ elif kind not in {'reasoning', 'user_message', 'checkpoint'}:
231
+ # Secret and approval payloads are deliberately never normalized into text.
232
+ coverage['projection_gaps'] += 1
233
+ if status == 'completed' and completed:
234
+ emit('boundary', 'turn_complete', run, completed, key, provider)
235
+ else:
236
+ coverage['incomplete_runs'] += 1
237
+ run_coverage[key] = {'source_incomplete': bool(coverage['byte_cap_reached']) or any(
238
+ coverage[name] > before[name] for name in (
239
+ 'projection_gaps', 'incomplete_runs', 'missing_timestamps')),
240
+ 'missing_timestamps': coverage['missing_timestamps'] - before['missing_timestamps']}
241
+ totals['t3_byte_capped_threads'] += bool(coverage['byte_cap_reached'])
242
+ if not events:
243
+ return None
244
+ # Keep each app run together even when provider clocks overlap during a handoff.
245
+ order = {r['key']: index for index, r in enumerate(runs)}
246
+ events.sort(key=lambda e: (order[e['run_id']], e['timestamp'],
247
+ e['kind'] == 'boundary', e['kind'] == 'reply'))
248
+ calls = {e['call_id'] for e in events if e['kind'] == 'call'}
249
+ results = {e['call_id'] for e in events if e['kind'] == 'result'}
250
+ state: dict[str, Any] = dict(coverage)
251
+ state['run_coverage'] = run_coverage
252
+ state.update(calls=len(calls), matched_results=len(calls & results),
253
+ unmatched_calls=len(calls - results), orphan_results=len(results - calls),
254
+ truncated_events=coverage['truncated_events'],
255
+ byte_cap_reached=bool(coverage['byte_cap_reached']),
256
+ source_incomplete=bool(coverage['projection_gaps'] or coverage['incomplete_runs']
257
+ or coverage['byte_cap_reached']))
258
+ state['complete'] = not any(state.get(k) for k in (
259
+ 'unmatched_calls', 'orphan_results', 'truncated_events', 'byte_cap_reached',
260
+ 'source_incomplete', 'missing_timestamps'))
261
+ return {'version': VERSION, 'agent': 't3', 'session_id': 't3:' + thread,
262
+ 'cwd': cwd, 'origin': 'interactive', 'model': None,
263
+ 'providers': sorted(seen_providers), 'native_sessions': sorted(native),
264
+ 'instruction_exposure': {'status': 'unknown',
265
+ 'reason': 'Project files alone do not prove past instruction delivery.'},
266
+ 'events': events, 'coverage': state,
267
+ 'source': {'path': str(path), 'format': 't3_projection_v2',
268
+ 'hash_scope': 'selected logical projection rows, not database file bytes',
269
+ 'sha256': _hash(captured), 'bytes': used, 'ranges': []}}