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,490 @@
1
+ """T3 app activity from its read-only v2 projection, after an explicit metric cutover."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sqlite3
7
+ from contextlib import contextmanager
8
+ from dataclasses import dataclass
9
+ from datetime import datetime, timezone
10
+ from pathlib import Path
11
+ from typing import Any, Collection, Iterator
12
+
13
+ from ..config import Config
14
+ from ..event import (
15
+ ActivityEvent,
16
+ Batch,
17
+ CollectorUnavailable,
18
+ EventSession,
19
+ Row,
20
+ RunOrigin,
21
+ UsageEvent,
22
+ make_event_id,
23
+ parse_ts,
24
+ )
25
+ from . import codex
26
+ from ._util import project_name
27
+ from .activity_common import first_record, human_event, ms_between
28
+
29
+ NAME = "t3"
30
+ _PREFIX = "orchestration_v2_projection_"
31
+ _MAX_ROWS = 100_000
32
+ _MAX_RECORD_BYTES = 1024 * 1024
33
+ _MAX_QUERY_BYTES = 16 * 1024 * 1024
34
+ _PAGE = 500
35
+ _DRIVERS = {"codex": "codex", "claudeAgent": "claude_code"}
36
+
37
+
38
+ def database_path(home: Path) -> Path:
39
+ return home / ".t3/userdata/statev2.sqlite"
40
+
41
+
42
+ def _stamp(value: object) -> datetime:
43
+ stamp = parse_ts(value)
44
+ if stamp is None or stamp.tzinfo is None:
45
+ raise ValueError("missing timezone-aware timestamp")
46
+ return stamp
47
+
48
+
49
+ def _payload(value: str) -> dict[str, Any]:
50
+ obj = json.loads(value)
51
+ if not isinstance(obj, dict):
52
+ raise ValueError("projection payload is not an object")
53
+ return obj
54
+
55
+
56
+ def confirmed_human(payload: dict[str, Any]) -> bool:
57
+ return payload.get("createdBy") == "user" and payload.get("creationSource") in {"web", "mobile"}
58
+
59
+
60
+ @contextmanager
61
+ def connection(home: Path) -> Iterator[sqlite3.Connection]:
62
+ """A live WAL-compatible snapshot; never create a database or read auth tables."""
63
+ con = sqlite3.connect(database_path(home).as_uri() + "?mode=ro", uri=True, timeout=1)
64
+ try:
65
+ con.execute("PRAGMA query_only=ON")
66
+ con.execute("BEGIN")
67
+ yield con
68
+ finally:
69
+ con.close()
70
+
71
+
72
+ def _read(
73
+ con: sqlite3.Connection, query: str, params: tuple[Any, ...] = ()
74
+ ) -> list[tuple[Any, ...]]:
75
+ """Bound SQLite's returned cells before Python allocation; reject incomplete query results."""
76
+ description = con.execute(f"SELECT * FROM ({query}) LIMIT 0", params).description
77
+ assert description is not None
78
+ columns = []
79
+ for column in description:
80
+ name = '"' + column[0].replace('"', '""') + '"'
81
+ columns.extend(
82
+ [
83
+ f"CASE WHEN typeof({name}) IN ('text','blob') "
84
+ f"THEN substr(CAST({name} AS BLOB),1,{_MAX_RECORD_BYTES + 1}) ELSE {name} END",
85
+ f"typeof({name})",
86
+ ]
87
+ )
88
+ cursor = con.execute(f"SELECT {','.join(columns)} FROM ({query}) LIMIT {_MAX_ROWS + 1}", params)
89
+ rows: list[tuple[Any, ...]] = []
90
+ total = 0
91
+ for bounded in cursor:
92
+ values, types = bounded[::2], bounded[1::2]
93
+ size = sum(len(value) if isinstance(value, bytes) else 8 for value in values)
94
+ total += size
95
+ if len(rows) >= _MAX_ROWS or size > _MAX_RECORD_BYTES or total > _MAX_QUERY_BYTES:
96
+ raise ValueError("projection exceeds bounded read limit")
97
+ rows.append(
98
+ tuple(
99
+ value.decode("utf-8") if kind == "text" else value
100
+ for value, kind in zip(values, types)
101
+ )
102
+ )
103
+ return rows
104
+
105
+
106
+ @dataclass(frozen=True)
107
+ class Binding:
108
+ session_id: str
109
+ start: datetime
110
+ end: datetime
111
+ origin: RunOrigin = "interactive"
112
+
113
+
114
+ @dataclass
115
+ class Snapshot:
116
+ messages: list[tuple[Any, ...]]
117
+ runs: list[tuple[Any, ...]]
118
+ projects: dict[str, str | None]
119
+ bindings: dict[tuple[str, str], list[Binding]]
120
+ native_ids: dict[str, tuple[str, str]]
121
+ message_runs: dict[str, list[tuple[Any, ...]]]
122
+ tool_attrs: dict[str, dict[str, Any]]
123
+ covered_runs: set[str]
124
+ run_threads: dict[str, str]
125
+
126
+
127
+ def snapshot(con: sqlite3.Connection, since: datetime, *, include_text: bool = True) -> Snapshot:
128
+ cutoff = (since.isoformat(),)
129
+ current = (
130
+ f"WITH current_runs AS (SELECT run_id,thread_id,provider_thread_id "
131
+ f"FROM {_PREFIX}runs WHERE julianday(requested_at) >= julianday(?) "
132
+ "OR julianday(requested_at) IS NULL) "
133
+ )
134
+ raw_runs = _read(
135
+ con,
136
+ current
137
+ + f"SELECT run_id,thread_id,provider,provider_thread_id,status,requested_at,completed_at,"
138
+ "json_object('userMessageId',json_extract(payload_json,'$.userMessageId')) AS payload_json "
139
+ f"FROM {_PREFIX}runs WHERE run_id IN (SELECT run_id FROM current_runs) "
140
+ "ORDER BY completed_at,run_id",
141
+ cutoff,
142
+ )
143
+ projects = dict(
144
+ _read(
145
+ con,
146
+ current
147
+ + "SELECT project_id,workspace_root FROM projection_projects WHERE project_id IN "
148
+ f"(SELECT project_id FROM {_PREFIX}threads WHERE thread_id IN "
149
+ "(SELECT thread_id FROM current_runs))",
150
+ cutoff,
151
+ )
152
+ )
153
+ thread_projects = {}
154
+ for tid, pid, raw in _read(
155
+ con,
156
+ current + "SELECT thread_id,project_id,"
157
+ "json_object('worktreePath',json_extract(payload_json,'$.worktreePath')) AS payload_json "
158
+ f"FROM {_PREFIX}threads WHERE thread_id IN (SELECT thread_id FROM current_runs)",
159
+ cutoff,
160
+ ):
161
+ payload = _payload(raw)
162
+ thread_projects[tid] = project_name(payload.get("worktreePath") or projects.get(pid))
163
+ text = "json_extract(payload_json,'$.text')" if include_text else "NULL"
164
+ messages = []
165
+ proofs: dict[str, tuple[str, datetime, RunOrigin]] = {}
166
+ for row in _read(
167
+ con,
168
+ "SELECT rowid,message_id,thread_id,run_id,role,created_at,"
169
+ "json_object('createdBy',json_extract(payload_json,'$.createdBy'),"
170
+ "'creationSource',json_extract(payload_json,'$.creationSource'),"
171
+ f"'text',{text}) AS payload_json "
172
+ f"FROM {_PREFIX}messages WHERE role = 'user' AND "
173
+ "(julianday(created_at) >= julianday(?) OR julianday(created_at) IS NULL) ORDER BY rowid",
174
+ cutoff,
175
+ ):
176
+ payload = _payload(row[6])
177
+ stamp = _stamp(row[5])
178
+ if row[4] == "user" and stamp >= since:
179
+ origin: RunOrigin = (
180
+ "interactive"
181
+ if confirmed_human(payload)
182
+ else "automated"
183
+ if payload.get("createdBy") == "agent"
184
+ else "unknown"
185
+ )
186
+ proofs[row[1]] = row[2], stamp, origin
187
+ if origin == "interactive":
188
+ messages.append((*row[:6], payload))
189
+ native_ids = {}
190
+ native_threads = {}
191
+ for ptid, tid, raw in _read(
192
+ con,
193
+ current + "SELECT provider_thread_id,thread_id,json_object('nativeThreadRef',json_object("
194
+ "'driver',json_extract(payload_json,'$.nativeThreadRef.driver'),"
195
+ "'nativeId',json_extract(payload_json,'$.nativeThreadRef.nativeId'),"
196
+ "'strength',json_extract(payload_json,'$.nativeThreadRef.strength'))) AS payload_json "
197
+ f"FROM {_PREFIX}provider_threads WHERE provider_thread_id IN "
198
+ "(SELECT provider_thread_id FROM current_runs)",
199
+ cutoff,
200
+ ):
201
+ ref = _payload(raw).get("nativeThreadRef")
202
+ if isinstance(ref, dict) and ref.get("strength") == "strong":
203
+ agent, sid = _DRIVERS.get(str(ref.get("driver"))), ref.get("nativeId")
204
+ if agent and isinstance(sid, str) and sid:
205
+ native_ids[ptid] = agent, sid
206
+ native_threads[ptid] = tid
207
+ runs: list[tuple[Any, ...]] = []
208
+ message_runs: dict[str, list[tuple[Any, ...]]] = {}
209
+ bindings: dict[tuple[str, str], list[Binding]] = {}
210
+ run_bindings: dict[str, tuple[str, str]] = {}
211
+ run_threads: dict[str, str] = {}
212
+ for row in raw_runs:
213
+ payload = _payload(row[7])
214
+ proof = proofs.get(str(payload.get("userMessageId")))
215
+ if not proof or proof[0] != row[1]:
216
+ continue
217
+ start = min(proof[1], _stamp(row[5]))
218
+ if start < since:
219
+ continue
220
+ end = _stamp(row[6]) if row[6] else datetime.now(timezone.utc)
221
+ if end < start:
222
+ raise ValueError("run ends before its human prompt")
223
+ run_threads[row[0]] = row[1]
224
+ if proof[2] == "interactive":
225
+ runs.append(row)
226
+ message_runs.setdefault(str(payload.get("userMessageId")), []).append(row)
227
+ key = native_ids.get(row[3])
228
+ if key and native_threads.get(row[3]) == row[1]:
229
+ run_bindings[row[0]] = key
230
+ bindings.setdefault(key, []).append(Binding("t3:" + row[1], start, end, proof[2]))
231
+ # A native identity bound to several app threads is not evidence of one canonical session.
232
+ bindings = {
233
+ key: spans
234
+ for key, spans in bindings.items()
235
+ if len({span.session_id for span in spans}) == 1
236
+ }
237
+ tool_attrs: dict[str, dict[str, Any]] = {}
238
+ if con.execute(
239
+ "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (_PREFIX + "turn_items",)
240
+ ).fetchone():
241
+ for runid, kind, status, exit_code in _read(
242
+ con,
243
+ current + f"SELECT run_id,type,status,json_extract(payload_json,'$.exitCode') "
244
+ f"FROM {_PREFIX}turn_items WHERE run_id IN (SELECT run_id FROM current_runs) "
245
+ "AND type IN ('command_execution','dynamic_tool','file_change')",
246
+ cutoff,
247
+ ):
248
+ attrs = tool_attrs.setdefault(runid, {"tool_calls": 0, "tool_errors": 0, "by_tool": {}})
249
+ attrs["tool_calls"] += 1
250
+ attrs["tool_errors"] += status == "failed" or (
251
+ type(exit_code) is int and exit_code != 0
252
+ )
253
+ attrs["by_tool"][kind] = attrs["by_tool"].get(kind, 0) + 1
254
+ covered_runs = {rid for rid, key in run_bindings.items() if key in bindings}
255
+ return Snapshot(
256
+ messages,
257
+ runs,
258
+ thread_projects,
259
+ bindings,
260
+ native_ids,
261
+ message_runs,
262
+ tool_attrs,
263
+ covered_runs,
264
+ run_threads,
265
+ )
266
+
267
+
268
+ def _since(cfg: Config) -> datetime:
269
+ if cfg.t3_activity_since is None:
270
+ raise CollectorUnavailable(
271
+ "t3: set t3_activity_since to an approved metric cutover timestamp"
272
+ )
273
+ try:
274
+ return _stamp(cfg.t3_activity_since)
275
+ except ValueError as exc:
276
+ raise CollectorUnavailable(
277
+ "t3: t3_activity_since needs a timezone-aware ISO timestamp"
278
+ ) from exc
279
+
280
+
281
+ def native_bindings(cfg: Config) -> dict[tuple[str, str], list[Binding]]:
282
+ """Read app proof once per native collector pass, without blocking native collection."""
283
+ if "t3" not in cfg.agents or not cfg.t3_activity_since or not database_path(cfg.home).exists():
284
+ return {}
285
+ try:
286
+ with connection(cfg.home) as con:
287
+ return snapshot(con, _since(cfg), include_text=False).bindings
288
+ except (OSError, sqlite3.Error, ValueError, TypeError, CollectorUnavailable) as exc:
289
+ # T3 reports its own degraded heartbeat; an unavailable app never blocks native usage.
290
+ import warnings
291
+
292
+ warnings.warn(
293
+ f"t3: native session linking unavailable ({type(exc).__name__})", stacklevel=2
294
+ )
295
+ return {}
296
+
297
+
298
+ def native_clients(cfg: Config) -> set[tuple[str, str]]:
299
+ """Client provenance can quarantine T3 Codex mirrors before a strong app binding exists."""
300
+ if "t3" not in cfg.agents or not cfg.t3_activity_since:
301
+ return set()
302
+ clients = set()
303
+ # shortcut: the native thread stays T3-owned after cutover; direct CLI resumes need per-launch provenance.
304
+ for path in codex.session_files(cfg.home):
305
+ head = first_record(path)
306
+ payload = head.get("payload") if head and head.get("type") == "session_meta" else None
307
+ if isinstance(payload, dict) and payload.get("originator") == "T3 Code":
308
+ sid = payload.get("id") or payload.get("session_id")
309
+ if isinstance(sid, str):
310
+ clients.add(("codex", sid))
311
+ return clients
312
+
313
+
314
+ def canonicalize(
315
+ rows: list[Row],
316
+ bindings: dict[tuple[str, str], list[Binding]],
317
+ clients: Collection[tuple[str, str]] = (),
318
+ since: datetime | None = None,
319
+ ) -> list[Row]:
320
+ """Map proven native intervals and omit only their app-mirrored human rows."""
321
+ out: list[Row] = []
322
+ for row in rows:
323
+ if not isinstance(row, (UsageEvent, ActivityEvent)):
324
+ out.append(row)
325
+ continue
326
+ if isinstance(row, ActivityEvent) and row.kind == "link" \
327
+ and row.attrs.get("run_origin") in {"automated", "subagent"}:
328
+ out.append(row)
329
+ continue
330
+ sess = row.session if isinstance(row, UsageEvent) else None
331
+ sid = (
332
+ sess.session_id if sess else row.session_id if isinstance(row, ActivityEvent) else None
333
+ )
334
+ stamp = parse_ts(row.ts)
335
+ spans = bindings.get((row.agent, sid), []) if isinstance(sid, str) else []
336
+ matches = [
337
+ span for span in spans if stamp and stamp.tzinfo and span.start <= stamp <= span.end
338
+ ]
339
+ match = matches[0] if matches else None
340
+ if match and len({span.origin for span in matches}) > 1:
341
+ match = Binding(match.session_id, match.start, match.end, "unknown")
342
+ if (
343
+ not match
344
+ and (row.agent, sid) in clients
345
+ and stamp
346
+ and stamp.tzinfo
347
+ and since
348
+ and stamp >= since
349
+ ):
350
+ if isinstance(row, UsageEvent):
351
+ if row.kind == "human":
352
+ continue
353
+ if sess and sess.run_origin not in {"automated", "subagent"}:
354
+ sess.run_origin = "unknown"
355
+ elif row.kind in {"steer", "turn"}:
356
+ continue
357
+ elif row.kind == "link":
358
+ row.attrs["run_origin"] = "unknown"
359
+ elif match and match.origin != "interactive":
360
+ if isinstance(row, UsageEvent):
361
+ if row.kind == "human":
362
+ continue
363
+ if sess and sess.run_origin not in {"automated", "subagent"}:
364
+ sess.run_origin = match.origin
365
+ elif row.kind in {"steer", "turn"}:
366
+ continue
367
+ elif row.kind == "link":
368
+ row.attrs["run_origin"] = match.origin
369
+ elif match and not (sess and sess.run_origin in {"automated", "subagent"}):
370
+ if isinstance(row, UsageEvent):
371
+ if row.kind == "human":
372
+ continue
373
+ if sess:
374
+ sess.session_id = match.session_id
375
+ sess.run_origin = "interactive"
376
+ elif isinstance(row, ActivityEvent):
377
+ if row.kind in {"steer", "turn"}:
378
+ continue
379
+ row.session_id = match.session_id
380
+ if row.kind == "link":
381
+ row.attrs["run_origin"] = "interactive"
382
+ out.append(row)
383
+ return out
384
+
385
+
386
+ def collect(cfg: Config, wm: dict[str, Any]) -> Iterator[Batch]:
387
+ if not database_path(cfg.home).exists() and not cfg.t3_activity_since:
388
+ return
389
+ since = _since(cfg)
390
+ try:
391
+ with connection(cfg.home) as con:
392
+ data = snapshot(con, since)
393
+ sent_messages = set(wm.get("message_ids", []))
394
+ sent_runs = set(wm.get("run_ids", []))
395
+ ambiguous = set()
396
+ eligible: set[str] = set()
397
+ for mid, runs in data.message_runs.items():
398
+ if all(run[0] in data.covered_runs for run in runs):
399
+ eligible.add(mid)
400
+ else:
401
+ ambiguous.add(mid)
402
+ pending: list[tuple[str, str, list[Row]]] = []
403
+ for rid, mid, tid, runid, role, ts, payload in data.messages:
404
+ if mid not in data.message_runs:
405
+ # A human steer into an agent-started run is proved by that run's binding too.
406
+ if data.run_threads.get(runid) == tid and runid in data.covered_runs:
407
+ eligible.add(mid)
408
+ if mid not in eligible:
409
+ ambiguous.add(mid)
410
+ continue
411
+ if mid in sent_messages:
412
+ continue
413
+ sid = "t3:" + tid
414
+ text = payload.get("text") if isinstance(payload.get("text"), str) else ""
415
+ sess = EventSession(sid, None, "interactive", runid)
416
+ pending.append(
417
+ (
418
+ "message_ids",
419
+ mid,
420
+ [
421
+ human_event(NAME, (mid,), ts, sess, data.projects.get(tid)),
422
+ ActivityEvent(
423
+ make_event_id(NAME, "steer", mid),
424
+ ts,
425
+ NAME,
426
+ "steer",
427
+ sid,
428
+ runid,
429
+ {
430
+ "via": "typed",
431
+ "words": len(text.split()),
432
+ "chars": len(text),
433
+ },
434
+ ),
435
+ ],
436
+ )
437
+ )
438
+ for rid, tid, provider, ptid, status, start, end, raw in data.runs:
439
+ if status != "completed" or not end or rid in sent_runs:
440
+ continue
441
+ if rid not in data.covered_runs:
442
+ continue
443
+ pending.append(
444
+ (
445
+ "run_ids",
446
+ rid,
447
+ [
448
+ ActivityEvent(
449
+ make_event_id(NAME, "turn", rid),
450
+ end,
451
+ NAME,
452
+ "turn",
453
+ "t3:" + tid,
454
+ rid,
455
+ {
456
+ "duration_ms": ms_between(start, end),
457
+ **data.tool_attrs.get(rid, {}),
458
+ },
459
+ )
460
+ ],
461
+ )
462
+ )
463
+ for offset in range(0, len(pending), _PAGE):
464
+ page = pending[offset : offset + _PAGE]
465
+ rows = [row for key, value, batch in page for row in batch]
466
+ delivered = [(key, value) for key, value, batch in page]
467
+
468
+ def advance(delivered: list[tuple[str, str]] = delivered) -> None:
469
+ for key, value in delivered:
470
+ ids = wm.setdefault(key, [])
471
+ if value not in ids:
472
+ ids.append(value)
473
+
474
+ yield rows, advance
475
+ if ambiguous:
476
+ raise CollectorUnavailable(
477
+ f"t3: {len(ambiguous)} human messages omitted, native overlap is unproved"
478
+ )
479
+ except (OSError, sqlite3.Error, ValueError, TypeError) as exc:
480
+ raise CollectorUnavailable("t3: projection database is unavailable or invalid") from exc
481
+
482
+
483
+ def describe(cfg: Config, wm: dict[str, Any]) -> str:
484
+ if not database_path(cfg.home).exists() and not cfg.t3_activity_since:
485
+ return "not installed"
486
+ if not database_path(cfg.home).exists():
487
+ return "degraded: T3 database is unavailable"
488
+ if not cfg.t3_activity_since:
489
+ return "degraded: t3_activity_since is not configured"
490
+ return f"activity since {cfg.t3_activity_since}; {len(wm.get('message_ids', []))} acknowledged human messages"