@openai/codex-security 0.1.4 → 0.1.6

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 (106) hide show
  1. package/README.md +127 -13
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +8 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +6 -0
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
  6. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  8. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  9. package/_bundled_plugin/preflight/capability-profiles.toml +0 -57
  10. package/_bundled_plugin/references/config-preflight.md +1 -1
  11. package/_bundled_plugin/references/final-report.md +15 -7
  12. package/_bundled_plugin/references/finding-detail-fields.md +10 -2
  13. package/_bundled_plugin/references/scan-artifacts.md +11 -9
  14. package/_bundled_plugin/references/scan-contract.md +3 -1
  15. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +42 -0
  16. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +100 -0
  17. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +181 -0
  18. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +166 -0
  19. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +120 -0
  20. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +83 -0
  21. package/_bundled_plugin/schemas/tools/review-items.schema.json +80 -0
  22. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +572 -0
  23. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +18 -0
  24. package/_bundled_plugin/scripts/deep_scan_config.py +11 -3
  25. package/_bundled_plugin/scripts/deep_scan_workbench.py +153 -133
  26. package/_bundled_plugin/scripts/finalize_scan_contract.py +39 -0
  27. package/_bundled_plugin/scripts/generate_in_scope_files.py +134 -0
  28. package/_bundled_plugin/scripts/workbench_cli.py +33 -1
  29. package/_bundled_plugin/scripts/workbench_db.py +181 -118
  30. package/_bundled_plugin/scripts/workbench_feedback.py +2 -0
  31. package/_bundled_plugin/scripts/workbench_native_indexes.py +5 -49
  32. package/_bundled_plugin/scripts/workbench_progress.py +86 -3
  33. package/_bundled_plugin/scripts/workbench_remediation.py +19 -1
  34. package/_bundled_plugin/scripts/workbench_scan_history.py +7 -1
  35. package/_bundled_plugin/scripts/workbench_scan_start.py +11 -5
  36. package/_bundled_plugin/scripts/workbench_scan_usage.py +557 -0
  37. package/_bundled_plugin/scripts/workbench_schema.py +501 -0
  38. package/_bundled_plugin/scripts/workbench_target.py +14 -1
  39. package/_bundled_plugin/scripts/workbench_validation.py +117 -13
  40. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -4
  41. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +34 -28
  42. package/_bundled_plugin/skills/finding-discovery/SKILL.md +1 -1
  43. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -8
  44. package/_bundled_plugin/skills/security-scan/SKILL.md +16 -9
  45. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +26 -14
  46. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +1 -1
  47. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  48. package/_bundled_plugin/skills/validation/SKILL.md +5 -5
  49. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +145 -227
  50. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +53 -68
  51. package/dist/api.d.ts +30 -8
  52. package/dist/api.d.ts.map +1 -1
  53. package/dist/api.js +438 -66
  54. package/dist/api.js.map +1 -1
  55. package/dist/auth.d.ts.map +1 -1
  56. package/dist/auth.js +262 -44
  57. package/dist/auth.js.map +1 -1
  58. package/dist/cli.d.ts +4 -3
  59. package/dist/cli.d.ts.map +1 -1
  60. package/dist/cli.js +713 -148
  61. package/dist/cli.js.map +1 -1
  62. package/dist/config.d.ts +28 -0
  63. package/dist/config.d.ts.map +1 -1
  64. package/dist/config.js +39 -2
  65. package/dist/config.js.map +1 -1
  66. package/dist/contract.d.ts.map +1 -1
  67. package/dist/contract.js +14 -0
  68. package/dist/contract.js.map +1 -1
  69. package/dist/cost.d.ts +7 -0
  70. package/dist/cost.d.ts.map +1 -1
  71. package/dist/cost.js +397 -26
  72. package/dist/cost.js.map +1 -1
  73. package/dist/errors.d.ts +2 -0
  74. package/dist/errors.d.ts.map +1 -1
  75. package/dist/errors.js +48 -0
  76. package/dist/errors.js.map +1 -1
  77. package/dist/index.d.ts +3 -2
  78. package/dist/index.d.ts.map +1 -1
  79. package/dist/index.js.map +1 -1
  80. package/dist/multiscan.d.ts +1 -0
  81. package/dist/multiscan.d.ts.map +1 -1
  82. package/dist/multiscan.js +5 -7
  83. package/dist/multiscan.js.map +1 -1
  84. package/dist/runtime.d.ts +40 -1
  85. package/dist/runtime.d.ts.map +1 -1
  86. package/dist/runtime.js +742 -46
  87. package/dist/runtime.js.map +1 -1
  88. package/dist/scan-activity.d.ts +13 -0
  89. package/dist/scan-activity.d.ts.map +1 -0
  90. package/dist/scan-activity.js +319 -0
  91. package/dist/scan-activity.js.map +1 -0
  92. package/dist/scan-dashboard.d.ts +47 -0
  93. package/dist/scan-dashboard.d.ts.map +1 -0
  94. package/dist/scan-dashboard.js +444 -0
  95. package/dist/scan-dashboard.js.map +1 -0
  96. package/dist/scan-history-renderer.d.ts.map +1 -1
  97. package/dist/scan-history-renderer.js +4 -1
  98. package/dist/scan-history-renderer.js.map +1 -1
  99. package/dist/version.d.ts +1 -1
  100. package/dist/version.js +1 -1
  101. package/dist/version.js.map +1 -1
  102. package/dist/worker-progress.d.ts +7 -0
  103. package/dist/worker-progress.d.ts.map +1 -1
  104. package/dist/worker-progress.js +68 -0
  105. package/dist/worker-progress.js.map +1 -1
  106. package/package.json +3 -3
@@ -0,0 +1,557 @@
1
+ """Measure scan-owned Codex token usage from the live thread graph."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import os
8
+ import re
9
+ import sqlite3
10
+ import sys
11
+ import uuid
12
+ from dataclasses import dataclass
13
+ from datetime import datetime, timezone
14
+ from pathlib import Path
15
+ from typing import Any, Mapping
16
+
17
+ TOKEN_FIELDS = {
18
+ "input_tokens": "inputTokens",
19
+ "cached_input_tokens": "cachedInputTokens",
20
+ "cache_write_input_tokens": "cacheWriteInputTokens",
21
+ "output_tokens": "outputTokens",
22
+ "reasoning_output_tokens": "reasoningOutputTokens",
23
+ "total_tokens": "totalTokens",
24
+ }
25
+ STATE_DATABASE_NAME = re.compile(r"state_(\d+)\.sqlite")
26
+ STATE_DATABASE_TIMEOUT_SECONDS = 1.0
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class RolloutSession:
31
+ thread_id: str
32
+ parent_thread_id: str | None
33
+ path: Path
34
+
35
+
36
+ def stored_scan_cost_fields(value: str | None) -> dict[str, Any]:
37
+ """Project measured usage without changing the existing legacy cost contract."""
38
+
39
+ if value is None:
40
+ return {}
41
+ stored = json.loads(value, parse_constant=_reject_nonstandard_json_number)
42
+ if not isinstance(stored, dict):
43
+ return {}
44
+ if "usage" not in stored:
45
+ return {"cost": stored}
46
+ return {
47
+ "usage": stored["usage"],
48
+ **({"cost": stored["cost"]} if isinstance(stored.get("cost"), dict) else {}),
49
+ }
50
+
51
+
52
+ def measured_scan_cost_json(usage: Mapping[str, Any]) -> str:
53
+ """Keep usage in the already-migrated scans.cost_json column."""
54
+
55
+ return json.dumps({"usage": dict(usage)}, separators=(",", ":"), allow_nan=False)
56
+
57
+
58
+ def collect_scan_usage(
59
+ connection: sqlite3.Connection,
60
+ scan: sqlite3.Row,
61
+ *,
62
+ thread_id: str | None = None,
63
+ completed_at: str | None = None,
64
+ ) -> dict[str, Any]:
65
+ """Count only complete, attributable rollout events inside this scan's window."""
66
+
67
+ roots = _scan_root_thread_ids(connection, scan, thread_id)
68
+ if not roots:
69
+ return _unavailable_usage("scan_thread_unavailable")
70
+
71
+ state_database = _codex_state_database()
72
+ if state_database is None:
73
+ return _unavailable_usage("codex_state_unavailable")
74
+
75
+ started_at = _timestamp(scan["started_at"])
76
+ stopped_at = _timestamp(completed_at or scan["completed_at"])
77
+ if started_at is None:
78
+ return _unavailable_usage("scan_window_unavailable")
79
+
80
+ warnings: set[str] = set()
81
+ try:
82
+ sessions, missing_thread_ids = _discover_rollout_sessions(
83
+ state_database,
84
+ roots,
85
+ warnings,
86
+ )
87
+ except (OSError, sqlite3.Error, ValueError):
88
+ return _unavailable_usage("codex_state_unavailable")
89
+
90
+ if not sessions:
91
+ return _unavailable_usage("scan_thread_unavailable", warnings=warnings)
92
+
93
+ total = _empty_token_usage()
94
+ observed_thread_count = 0
95
+ accepted_thread_ids: set[str] = set()
96
+ excluded_thread_ids: set[str] = set()
97
+ for session in sessions:
98
+ if session.parent_thread_id in excluded_thread_ids:
99
+ excluded_thread_ids.add(session.thread_id)
100
+ continue
101
+ if (
102
+ session.parent_thread_id is not None
103
+ and session.parent_thread_id not in accepted_thread_ids
104
+ ):
105
+ missing_thread_ids.add(session.thread_id)
106
+ warnings.add("thread_lineage_incomplete")
107
+ continue
108
+ try:
109
+ session_usage, session_warnings = _read_rollout_usage(
110
+ session,
111
+ started_at=started_at,
112
+ completed_at=stopped_at,
113
+ )
114
+ except (OSError, UnicodeError, ValueError):
115
+ missing_thread_ids.add(session.thread_id)
116
+ warnings.add("rollout_unavailable")
117
+ continue
118
+ if "thread_outside_scan_window" in session_warnings:
119
+ excluded_thread_ids.add(session.thread_id)
120
+ continue
121
+ warnings.update(session_warnings)
122
+ if "thread_identity_mismatch" in session_warnings or (
123
+ "thread_ownership_unavailable" in session_warnings
124
+ ):
125
+ missing_thread_ids.add(session.thread_id)
126
+ continue
127
+ accepted_thread_ids.add(session.thread_id)
128
+ observed_thread_count += 1
129
+ _add_token_usage(total, session_usage)
130
+
131
+ if not observed_thread_count:
132
+ return _unavailable_usage("scan_thread_unavailable", warnings=warnings)
133
+
134
+ result: dict[str, Any] = {
135
+ "coverage": "partial" if missing_thread_ids or warnings else "complete",
136
+ "source": "codex_rollout",
137
+ **total,
138
+ "threadCount": observed_thread_count,
139
+ }
140
+ if missing_thread_ids:
141
+ result["missingThreadCount"] = len(missing_thread_ids)
142
+ if warnings:
143
+ result["warnings"] = sorted(warnings)
144
+ return result
145
+
146
+
147
+ def _scan_root_thread_ids(
148
+ connection: sqlite3.Connection,
149
+ scan: sqlite3.Row,
150
+ supplied_thread_id: str | None,
151
+ ) -> list[str]:
152
+ candidates: list[str | None] = [supplied_thread_id]
153
+ if "continuation_thread_id" in scan.keys():
154
+ candidates.append(scan["continuation_thread_id"])
155
+ if "deep_scan_owner_thread_id" in scan.keys():
156
+ candidates.append(scan["deep_scan_owner_thread_id"])
157
+ workspace = connection.execute(
158
+ "SELECT thread_id FROM workspaces WHERE id = ?",
159
+ (scan["workspace_id"],),
160
+ ).fetchone()
161
+ if workspace is not None:
162
+ candidates.append(workspace["thread_id"])
163
+ if scan["mode"] == "deep":
164
+ candidates.extend(
165
+ row["sdk_thread_id"]
166
+ for row in connection.execute(
167
+ """
168
+ SELECT DISTINCT sdk_thread_id
169
+ FROM deep_scan_workers
170
+ WHERE scan_id = ? AND sdk_thread_id IS NOT NULL
171
+ ORDER BY sdk_thread_id
172
+ """,
173
+ (scan["id"],),
174
+ )
175
+ )
176
+ roots: list[str] = []
177
+ seen: set[str] = set()
178
+ for candidate in candidates:
179
+ if isinstance(candidate, str) and candidate.strip() and candidate not in seen:
180
+ roots.append(candidate)
181
+ seen.add(candidate)
182
+ return roots
183
+
184
+
185
+ def _codex_state_database() -> Path | None:
186
+ configured_database = os.environ.get("CODEX_STATE_DB", "").strip()
187
+ if configured_database:
188
+ path = Path(configured_database).expanduser()
189
+ return path.resolve() if path.is_file() and os.access(path, os.R_OK) else None
190
+
191
+ configured_home = os.environ.get("CODEX_HOME", "").strip()
192
+ codex_home = Path(configured_home).expanduser() if configured_home else Path.home() / ".codex"
193
+ configured_sqlite_home = os.environ.get("CODEX_SQLITE_HOME", "").strip()
194
+ search_roots = [
195
+ *([Path(configured_sqlite_home).expanduser()] if configured_sqlite_home else []),
196
+ codex_home,
197
+ codex_home / "sqlite",
198
+ ]
199
+ seen: set[Path] = set()
200
+ for search_root in search_roots:
201
+ try:
202
+ resolved_root = search_root.resolve()
203
+ if resolved_root in seen:
204
+ continue
205
+ seen.add(resolved_root)
206
+ candidates = [
207
+ (int(match.group(1)), path)
208
+ for path in resolved_root.glob("state_*.sqlite")
209
+ if (match := STATE_DATABASE_NAME.fullmatch(path.name)) is not None
210
+ and path.is_file()
211
+ and os.access(path, os.R_OK)
212
+ ]
213
+ except (OSError, RuntimeError, ValueError):
214
+ continue
215
+ if candidates:
216
+ return max(candidates, key=lambda item: item[0])[1].resolve()
217
+ return None
218
+
219
+
220
+ def _discover_rollout_sessions(
221
+ state_database: Path,
222
+ roots: list[str],
223
+ warnings: set[str],
224
+ ) -> tuple[list[RolloutSession], set[str]]:
225
+ database = sqlite3.connect(
226
+ state_database.as_uri() + "?mode=ro",
227
+ uri=True,
228
+ timeout=STATE_DATABASE_TIMEOUT_SECONDS,
229
+ )
230
+ try:
231
+ database.row_factory = sqlite3.Row
232
+ database.execute("PRAGMA query_only = ON")
233
+ _require_state_columns(database, "threads", {"id", "rollout_path"})
234
+ _require_state_columns(
235
+ database,
236
+ "thread_spawn_edges",
237
+ {"parent_thread_id", "child_thread_id"},
238
+ )
239
+ sessions: list[RolloutSession] = []
240
+ seen_thread_ids: set[str] = set()
241
+ missing_thread_ids: set[str] = set()
242
+ for root in roots:
243
+ row = database.execute(
244
+ "SELECT id, rollout_path FROM threads WHERE id = ?",
245
+ (root,),
246
+ ).fetchone()
247
+ if row is None:
248
+ missing_thread_ids.add(root)
249
+ warnings.add("scan_root_unavailable")
250
+ continue
251
+ if root not in seen_thread_ids:
252
+ path = _rollout_path(row["rollout_path"])
253
+ if path is None:
254
+ missing_thread_ids.add(root)
255
+ warnings.add("rollout_unavailable")
256
+ continue
257
+ sessions.append(RolloutSession(root, None, path))
258
+ seen_thread_ids.add(root)
259
+ descendants = database.execute(
260
+ """
261
+ WITH RECURSIVE descendants(
262
+ depth, parent_thread_id, child_thread_id, ancestry, cycle
263
+ ) AS (
264
+ SELECT
265
+ 1,
266
+ edges.parent_thread_id,
267
+ edges.child_thread_id,
268
+ '|' || edges.parent_thread_id || '|' || edges.child_thread_id || '|',
269
+ edges.parent_thread_id = edges.child_thread_id
270
+ FROM thread_spawn_edges AS edges
271
+ WHERE edges.parent_thread_id = ?
272
+
273
+ UNION ALL
274
+
275
+ SELECT
276
+ descendants.depth + 1,
277
+ edges.parent_thread_id,
278
+ edges.child_thread_id,
279
+ descendants.ancestry || edges.child_thread_id || '|',
280
+ instr(descendants.ancestry, '|' || edges.child_thread_id || '|') > 0
281
+ FROM thread_spawn_edges AS edges
282
+ JOIN descendants ON edges.parent_thread_id = descendants.child_thread_id
283
+ WHERE descendants.cycle = 0
284
+ )
285
+ SELECT
286
+ descendants.depth,
287
+ descendants.parent_thread_id,
288
+ descendants.child_thread_id,
289
+ descendants.cycle,
290
+ threads.rollout_path
291
+ FROM descendants
292
+ LEFT JOIN threads ON threads.id = descendants.child_thread_id
293
+ ORDER BY descendants.depth, descendants.child_thread_id
294
+ """,
295
+ (root,),
296
+ )
297
+ for descendant in descendants:
298
+ child_id = descendant["child_thread_id"]
299
+ parent_id = descendant["parent_thread_id"]
300
+ if not isinstance(child_id, str) or not isinstance(parent_id, str):
301
+ warnings.add("thread_lineage_incomplete")
302
+ continue
303
+ if descendant["cycle"]:
304
+ missing_thread_ids.add(child_id)
305
+ warnings.add("thread_lineage_cycle")
306
+ continue
307
+ if child_id in seen_thread_ids:
308
+ continue
309
+ path = _rollout_path(descendant["rollout_path"])
310
+ if path is None:
311
+ missing_thread_ids.add(child_id)
312
+ warnings.add("rollout_unavailable")
313
+ continue
314
+ sessions.append(RolloutSession(child_id, parent_id, path))
315
+ seen_thread_ids.add(child_id)
316
+ return sessions, missing_thread_ids
317
+ finally:
318
+ database.close()
319
+
320
+
321
+ def _require_state_columns(
322
+ connection: sqlite3.Connection,
323
+ table: str,
324
+ required: set[str],
325
+ ) -> None:
326
+ statements = {
327
+ "threads": "PRAGMA table_info(threads)",
328
+ "thread_spawn_edges": "PRAGMA table_info(thread_spawn_edges)",
329
+ }
330
+ columns = {str(row["name"]) for row in connection.execute(statements[table])}
331
+ if not required.issubset(columns):
332
+ raise ValueError("Codex state graph does not expose the required thread columns.")
333
+
334
+
335
+ def _rollout_path(value: object) -> Path | None:
336
+ if not isinstance(value, str) or not value:
337
+ return None
338
+ candidate = Path(value).expanduser()
339
+ if not candidate.is_absolute():
340
+ return None
341
+ try:
342
+ resolved = candidate.resolve(strict=True)
343
+ if not resolved.is_file():
344
+ return None
345
+
346
+ if resolved == candidate:
347
+ return resolved
348
+
349
+ if sys.platform == "darwin" and candidate.parts[1] in {"var", "tmp"}:
350
+ expected = Path("/private", *candidate.parts[1:])
351
+ if resolved == expected:
352
+ return resolved
353
+ except (OSError, RuntimeError):
354
+ return None
355
+ return None
356
+
357
+
358
+ def _read_rollout_usage(
359
+ session: RolloutSession,
360
+ *,
361
+ started_at: datetime,
362
+ completed_at: datetime | None,
363
+ ) -> tuple[dict[str, int], set[str]]:
364
+ total = _empty_token_usage()
365
+ warnings: set[str] = set()
366
+ previous = _empty_token_usage()
367
+ boundary_reached = False
368
+
369
+ with session.path.open("rb") as source:
370
+ for line_number, raw_line in enumerate(source, start=1):
371
+ if not raw_line.endswith(b"\n"):
372
+ warnings.add("rollout_record_incomplete")
373
+ continue
374
+ try:
375
+ event = json.loads(raw_line)
376
+ except (UnicodeError, ValueError):
377
+ if line_number == 1:
378
+ raise ValueError("The rollout session metadata is unreadable.") from None
379
+ if boundary_reached:
380
+ warnings.add("rollout_record_invalid")
381
+ continue
382
+ if not isinstance(event, dict):
383
+ if boundary_reached:
384
+ warnings.add("rollout_record_invalid")
385
+ continue
386
+ payload = event.get("payload")
387
+ if line_number == 1:
388
+ if event.get("type") != "session_meta" or not isinstance(payload, dict):
389
+ warnings.add("thread_identity_mismatch")
390
+ return total, warnings
391
+ recorded_id = payload.get("id") or payload.get("session_id")
392
+ if recorded_id != session.thread_id:
393
+ warnings.add("thread_identity_mismatch")
394
+ return total, warnings
395
+ recorded_parent = _session_parent_thread_id(payload)
396
+ if session.parent_thread_id is not None:
397
+ if recorded_parent != session.parent_thread_id:
398
+ warnings.add("thread_identity_mismatch")
399
+ return total, warnings
400
+ boundary_reached = (
401
+ session.parent_thread_id is None
402
+ and not recorded_parent
403
+ and not payload.get("forked_from_id")
404
+ )
405
+ continue
406
+
407
+ if not isinstance(payload, dict):
408
+ continue
409
+ if not boundary_reached:
410
+ if _is_owned_task_start(session.thread_id, event, payload):
411
+ task_started_at = _timestamp(event.get("timestamp"))
412
+ if task_started_at is None:
413
+ warnings.add("thread_ownership_unavailable")
414
+ return total, warnings
415
+ if task_started_at < started_at or (
416
+ completed_at is not None and task_started_at > completed_at
417
+ ):
418
+ warnings.add("thread_outside_scan_window")
419
+ return total, warnings
420
+ boundary_reached = True
421
+ elif event.get("type") == "event_msg" and payload.get("type") == "token_count":
422
+ inherited_usage = _token_snapshot(payload)
423
+ if inherited_usage is not None:
424
+ previous = inherited_usage
425
+ continue
426
+ if event.get("type") != "event_msg" or payload.get("type") != "token_count":
427
+ continue
428
+ timestamp = _timestamp(event.get("timestamp"))
429
+ snapshot = _token_snapshot(payload)
430
+ if timestamp is None or snapshot is None:
431
+ warnings.add("token_record_invalid")
432
+ continue
433
+ delta = {
434
+ key: value - previous[key] if value >= previous[key] else value
435
+ for key, value in snapshot.items()
436
+ }
437
+ previous = snapshot
438
+ if timestamp < started_at:
439
+ continue
440
+ if completed_at is not None and timestamp > completed_at:
441
+ continue
442
+ if delta["totalTokens"] <= 0:
443
+ continue
444
+ _add_token_usage(total, delta)
445
+
446
+ if not boundary_reached:
447
+ warnings.add("thread_ownership_unavailable")
448
+ return total, warnings
449
+
450
+
451
+ def _session_parent_thread_id(payload: Mapping[str, Any]) -> str | None:
452
+ source = payload.get("source")
453
+ if isinstance(source, dict):
454
+ subagent = source.get("subagent")
455
+ if isinstance(subagent, dict):
456
+ thread_spawn = subagent.get("thread_spawn")
457
+ if isinstance(thread_spawn, dict):
458
+ parent = thread_spawn.get("parent_thread_id")
459
+ if isinstance(parent, str) and parent:
460
+ return parent
461
+ for key in ("parent_thread_id", "forked_from_id"):
462
+ parent = payload.get(key)
463
+ if isinstance(parent, str) and parent:
464
+ return parent
465
+ return None
466
+
467
+
468
+ def _is_owned_task_start(
469
+ thread_id: str,
470
+ event: Mapping[str, Any],
471
+ payload: Mapping[str, Any],
472
+ ) -> bool:
473
+ if event.get("type") != "event_msg" or payload.get("type") != "task_started":
474
+ return False
475
+ turn_id = payload.get("turn_id")
476
+ if not isinstance(turn_id, str) or not turn_id:
477
+ return False
478
+ thread_timestamp = _uuid7_timestamp(thread_id)
479
+ turn_timestamp = _uuid7_timestamp(turn_id)
480
+ if thread_timestamp is None:
481
+ return True
482
+ return turn_timestamp is not None and turn_timestamp >= thread_timestamp
483
+
484
+
485
+ def _uuid7_timestamp(value: str) -> int | None:
486
+ try:
487
+ parsed = uuid.UUID(value)
488
+ except ValueError:
489
+ return None
490
+ return parsed.int >> 80 if parsed.version == 7 else None
491
+
492
+
493
+ def _token_snapshot(payload: Mapping[str, Any]) -> dict[str, int] | None:
494
+ info = payload.get("info")
495
+ if not isinstance(info, dict):
496
+ return None
497
+ usage = info.get("total_token_usage")
498
+ if not isinstance(usage, dict):
499
+ return None
500
+ result: dict[str, int] = {}
501
+ for source_key, result_key in TOKEN_FIELDS.items():
502
+ value = (
503
+ usage.get(source_key, usage.get("cache_write_tokens", 0))
504
+ if source_key == "cache_write_input_tokens"
505
+ else usage.get(source_key, 0)
506
+ )
507
+ if type(value) is not int or value < 0:
508
+ return None
509
+ if source_key in {"input_tokens", "output_tokens", "total_tokens"} and (
510
+ source_key not in usage
511
+ ):
512
+ return None
513
+ result[result_key] = value
514
+ if result["cachedInputTokens"] + result["cacheWriteInputTokens"] > result["inputTokens"]:
515
+ return None
516
+ result["totalTokens"] = result["inputTokens"] + result["outputTokens"]
517
+ return result
518
+
519
+
520
+ def _empty_token_usage() -> dict[str, int]:
521
+ return {field: 0 for field in TOKEN_FIELDS.values()}
522
+
523
+
524
+ def _add_token_usage(target: dict[str, int], addition: Mapping[str, int]) -> None:
525
+ for key in TOKEN_FIELDS.values():
526
+ target[key] += addition[key]
527
+
528
+
529
+ def _timestamp(value: object) -> datetime | None:
530
+ if not isinstance(value, str) or not value:
531
+ return None
532
+ try:
533
+ parsed = (
534
+ datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
535
+ if value.endswith("Z")
536
+ else datetime.fromisoformat(value)
537
+ )
538
+ except ValueError:
539
+ return None
540
+ return parsed.astimezone(timezone.utc) if parsed.tzinfo is not None else None
541
+
542
+
543
+ def _unavailable_usage(reason: str, *, warnings: set[str] | None = None) -> dict[str, Any]:
544
+ return {
545
+ "coverage": "unavailable",
546
+ "source": "codex_rollout",
547
+ "threadCount": 0,
548
+ "warnings": sorted({reason, *(warnings or set())}),
549
+ }
550
+
551
+
552
+ def _reject_nonstandard_json_number(value: str) -> None:
553
+ raise ValueError(f"invalid JSON number {value}")
554
+
555
+
556
+ if __name__ == "__main__":
557
+ argparse.ArgumentParser(description=__doc__).parse_args()