codex-agent-hour-tracker 0.1.0__py3-none-any.whl

agent_hour_tracker/__init__.py

@@ -0,0 +1,6 @@
+"""Privacy-preserving duration tracking for Codex session logs."""
+
+__all__ = ["METHODOLOGY_VERSION", "__version__"]
+
+__version__ = "0.1.0"
+METHODOLOGY_VERSION = "1"

agent_hour_tracker/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agent_hour_tracker/cli.py

@@ -0,0 +1,281 @@
+"""Command-line interface for the local agent-hour report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import TextIO
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import tzlocal
+
+from . import METHODOLOGY_VERSION, __version__
+from .metrics import build_report_metrics
+from .report import render_csv, render_share, render_text
+from .scanner import ScanDiagnostics, scan_sessions
+
+__all__ = ["main"]
+
+_MAX_MALFORMED_FILE_PATHS = 20
+_MAX_DISPLAYED_PATH_LENGTH = 120
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the agent-hour tracker CLI and return a process exit code."""
+
+    parser = _build_parser()
+    try:
+        arguments = parser.parse_args(argv)
+    except SystemExit as error:
+        return int(error.code)
+
+    if arguments.share and (
+        arguments.start is not None
+        or arguments.end is not None
+        or arguments.format is not None
+    ):
+        print(
+            "error: --share cannot be combined with --start, --end, or --format",
+            file=sys.stderr,
+        )
+        return 2
+
+    timezone = _resolve_timezone(arguments.timezone, sys.stderr)
+    if timezone is None:
+        return 2
+    report_range = _resolve_report_range(
+        None if arguments.share else arguments.start,
+        None if arguments.share else arguments.end,
+        _today_in_timezone(timezone),
+        sys.stderr,
+    )
+    if report_range is None:
+        return 2
+    start, end = report_range
+
+    sessions_dir = arguments.sessions_dir
+    if not sessions_dir.is_dir():
+        if arguments.share:
+            print(
+                "error: sessions directory is missing or not a directory",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"error: sessions directory is missing or not a directory: {sessions_dir}",
+                file=sys.stderr,
+            )
+        return 2
+
+    scan_result = scan_sessions(sessions_dir)
+    report = build_report_metrics(scan_result.turns, start, end, timezone)
+    if arguments.share:
+        sys.stdout.write(render_share(report, __version__, METHODOLOGY_VERSION))
+    elif arguments.format == "csv":
+        sys.stdout.write(render_csv(report))
+    else:
+        sys.stdout.write(render_text(report))
+    _write_diagnostics(scan_result.diagnostics, sys.stderr, share_safe=arguments.share)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-hours",
+        description="Report cumulative Codex agent-hours from local session metadata.",
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        type=Path,
+        default=Path.home() / ".codex" / "sessions",
+        help="Codex sessions directory (default: ~/.codex/sessions)",
+    )
+    parser.add_argument(
+        "--start",
+        default=None,
+        metavar="YYYY-MM-DD",
+        help="first report date, inclusive (default: 30 completed days)",
+    )
+    parser.add_argument(
+        "--end",
+        default=None,
+        metavar="YYYY-MM-DD",
+        help="last report date, inclusive (default: yesterday)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "csv"),
+        default=None,
+        help="report format (default: text; unavailable with --share)",
+    )
+    parser.add_argument(
+        "--share",
+        action="store_true",
+        help="render a sanitized Archive Score card for sharing (canonical 30-day range)",
+    )
+    parser.add_argument(
+        "--timezone",
+        default=None,
+        metavar="IANA_ZONE",
+        help="IANA timezone (default: discovered local timezone)",
+    )
+    return parser
+
+
+def _parse_date(value: str, label: str, stderr: TextIO) -> date | None:
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        print(f"error: invalid {label} date: {value!r}", file=stderr)
+        return None
+
+
+def _resolve_report_range(
+    start_value: str | None,
+    end_value: str | None,
+    today: date,
+    stderr: TextIO,
+) -> tuple[date, date] | None:
+    start = (
+        _parse_date(start_value, "start", stderr)
+        if start_value is not None
+        else None
+    )
+    if start_value is not None and start is None:
+        return None
+
+    end = (
+        _parse_date(end_value, "end", stderr)
+        if end_value is not None
+        else None
+    )
+    if end_value is not None and end is None:
+        return None
+
+    if end is None:
+        end = today - timedelta(days=1)
+    if start is None:
+        start = end - timedelta(days=29)
+
+    if end < start:
+        print("error: end date must not precede start date", file=stderr)
+        return None
+    return start, end
+
+
+def _resolve_timezone(value: str | None, stderr: TextIO) -> ZoneInfo | None:
+    if value is not None:
+        try:
+            return ZoneInfo(value)
+        except (ZoneInfoNotFoundError, ValueError):
+            print(f"error: invalid timezone: {value!r}", file=stderr)
+            return None
+
+    timezone_name, warning = _discover_timezone_name()
+    if warning:
+        print(
+            f"warning: using {timezone_name} for the local timezone",
+            file=stderr,
+        )
+    try:
+        return ZoneInfo(timezone_name)
+    except (ZoneInfoNotFoundError, TypeError, ValueError):
+        print("warning: local timezone is unavailable; using UTC", file=stderr)
+        return ZoneInfo("UTC")
+
+
+def _discover_timezone_name() -> tuple[str, bool]:
+    try:
+        timezone_name = tzlocal.get_localzone_name()
+    except Exception:
+        return "UTC", True
+    if not isinstance(timezone_name, str) or not timezone_name:
+        return "UTC", True
+    return timezone_name, False
+
+
+def _today_in_timezone(timezone: ZoneInfo) -> date:
+    return datetime.now(timezone).date()
+
+
+def _write_diagnostics(
+    diagnostics: ScanDiagnostics,
+    stderr: TextIO,
+    share_safe: bool = False,
+) -> None:
+    if share_safe:
+        if diagnostics.malformed_lines:
+            print(f"Malformed lines: {diagnostics.malformed_lines}", file=stderr)
+        if diagnostics.malformed_files:
+            print(f"Malformed files: {len(diagnostics.malformed_files)}", file=stderr)
+        if diagnostics.incomplete_turns:
+            print(f"Incomplete turns: {diagnostics.incomplete_turns}", file=stderr)
+        if diagnostics.unmatched_completions:
+            print(
+                f"Unmatched completions: {diagnostics.unmatched_completions}",
+                file=stderr,
+            )
+        if diagnostics.duration_fallbacks:
+            print(f"Duration fallbacks: {diagnostics.duration_fallbacks}", file=stderr)
+        if diagnostics.event_timing_fallbacks:
+            print(
+                f"Event timing fallbacks: {diagnostics.event_timing_fallbacks}",
+                file=stderr,
+            )
+        if diagnostics.duplicate_turns:
+            print(f"Duplicate turns: {diagnostics.duplicate_turns}", file=stderr)
+        if diagnostics.excluded_batch_turns:
+            print(
+                f"Excluded batch turns: {diagnostics.excluded_batch_turns}",
+                file=stderr,
+            )
+        return
+
+    if diagnostics.malformed_lines:
+        print(f"Malformed lines: {diagnostics.malformed_lines}", file=stderr)
+    if diagnostics.malformed_files:
+        malformed_files = sorted(diagnostics.malformed_files)
+        print(f"Malformed files: {len(malformed_files)}", file=stderr)
+        for path in malformed_files[:_MAX_MALFORMED_FILE_PATHS]:
+            print(f"  {_display_path(path)}", file=stderr)
+        omitted = len(malformed_files) - _MAX_MALFORMED_FILE_PATHS
+        if omitted > 0:
+            print(
+                f"  ... {omitted} malformed file paths omitted",
+                file=stderr,
+            )
+    if diagnostics.incomplete_turns:
+        print(f"Incomplete turns: {diagnostics.incomplete_turns}", file=stderr)
+    if diagnostics.unmatched_completions:
+        print(
+            f"Unmatched completions: {diagnostics.unmatched_completions}",
+            file=stderr,
+        )
+    if diagnostics.duration_fallbacks:
+        print(f"Duration fallbacks: {diagnostics.duration_fallbacks}", file=stderr)
+    if diagnostics.event_timing_fallbacks:
+        print(
+            f"Event timing fallbacks: {diagnostics.event_timing_fallbacks}",
+            file=stderr,
+        )
+    if diagnostics.duplicate_turns:
+        print(f"Duplicate turns: {diagnostics.duplicate_turns}", file=stderr)
+    if diagnostics.excluded_batch_turns:
+        print(
+            f"Excluded batch turns: {diagnostics.excluded_batch_turns}",
+            file=stderr,
+        )
+    if diagnostics.unknown_sources:
+        print("Unknown sources:", file=stderr)
+        for source, count in sorted(diagnostics.unknown_sources.items()):
+            print(f"  {source}: {count}", file=stderr)
+
+
+def _display_path(path: Path) -> str:
+    escaped = json.dumps(str(path), ensure_ascii=True)
+    if len(escaped) <= _MAX_DISPLAYED_PATH_LENGTH:
+        return escaped
+    return escaped[: _MAX_DISPLAYED_PATH_LENGTH - 4] + '..."'

agent_hour_tracker/metrics.py

@@ -0,0 +1,159 @@
+"""Aggregate completed turn durations into daily report metrics."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from math import ceil
+from statistics import median
+from zoneinfo import ZoneInfo
+
+from .scanner import CompletedTurn
+
+__all__ = ["DailyStat", "ReportMetrics", "build_report_metrics"]
+
+HISTOGRAM_LABELS = (
+    "0",
+    ">0 to <1",
+    "1 to <5",
+    "5 to <10",
+    "10 to <15",
+    "15 to <30",
+    "30 to <60",
+    "60+",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DailyStat:
+    """Agent-hours and completed-turn count for one calendar date."""
+
+    date: date
+    agent_hours: float
+    completed_turns: int
+
+
+@dataclass(frozen=True, slots=True)
+class ReportMetrics:
+    """Daily rows and summary statistics for an inclusive report range."""
+
+    days: tuple[DailyStat, ...]
+    total_agent_hours: float
+    mean_per_calendar_day: float
+    mean_per_active_day: float
+    median_agent_hours: float
+    p95_agent_hours: float
+    max_agent_hours: float
+    active_days: int
+    zero_days: int
+    days_above_15_hours: int
+    days_above_60_hours: int
+    histogram: OrderedDict[str, int]
+
+
+def build_report_metrics(
+    turns: list[CompletedTurn],
+    start: date,
+    end: date,
+    timezone: ZoneInfo,
+) -> ReportMetrics:
+    """Build daily and distribution metrics for an inclusive date range.
+
+    Each turn's full duration is assigned to the local date of its start,
+    independently of any other turn. Turns whose local start date falls
+    outside the requested range are ignored.
+
+    Raises:
+        ValueError: If ``end`` precedes ``start``.
+    """
+
+    if end < start:
+        raise ValueError("end date must not precede start date")
+
+    hours_by_date: dict[date, float] = {}
+    turns_by_date: dict[date, int] = {}
+    current = start
+    while current <= end:
+        hours_by_date[current] = 0.0
+        turns_by_date[current] = 0
+        if current == end:
+            break
+        current += timedelta(days=1)
+
+    for turn in turns:
+        try:
+            local_date = datetime.fromtimestamp(turn.started_at, timezone).date()
+        except (OSError, OverflowError, ValueError):
+            continue
+        if local_date not in hours_by_date:
+            continue
+        hours_by_date[local_date] += turn.duration_seconds / 3_600.0
+        turns_by_date[local_date] += 1
+
+    days = tuple(
+        DailyStat(day, hours_by_date[day], turns_by_date[day])
+        for day in hours_by_date
+    )
+    values = [day.agent_hours for day in days]
+    total_agent_hours = sum(values)
+    active_days = sum(value > 0.0 for value in values)
+    zero_days = sum(value == 0.0 for value in values)
+    day_count = len(values)
+
+    return ReportMetrics(
+        days=days,
+        total_agent_hours=total_agent_hours,
+        mean_per_calendar_day=total_agent_hours / day_count,
+        mean_per_active_day=(
+            total_agent_hours / active_days if active_days else 0.0
+        ),
+        median_agent_hours=float(median(values)),
+        p95_agent_hours=_percentile_95(values),
+        max_agent_hours=max(values),
+        active_days=active_days,
+        zero_days=zero_days,
+        days_above_15_hours=sum(value > 15.0 for value in values),
+        days_above_60_hours=sum(value > 60.0 for value in values),
+        histogram=_build_histogram(values),
+    )
+
+
+def _percentile_95(values: list[float]) -> float:
+    ordered = sorted(values)
+    if len(ordered) == 1:
+        return ordered[0]
+    position = (len(ordered) - 1) * 0.95
+    lower_index = int(position)
+    upper_index = ceil(position)
+    if lower_index == upper_index:
+        return ordered[lower_index]
+    weight = position - lower_index
+    return ordered[lower_index] + weight * (
+        ordered[upper_index] - ordered[lower_index]
+    )
+
+
+def _build_histogram(values: list[float]) -> OrderedDict[str, int]:
+    histogram: OrderedDict[str, int] = OrderedDict(
+        (label, 0) for label in HISTOGRAM_LABELS
+    )
+    for value in values:
+        if value == 0.0:
+            label = "0"
+        elif value < 1.0:
+            label = ">0 to <1"
+        elif value < 5.0:
+            label = "1 to <5"
+        elif value < 10.0:
+            label = "5 to <10"
+        elif value < 15.0:
+            label = "10 to <15"
+        elif value < 30.0:
+            label = "15 to <30"
+        elif value < 60.0:
+            label = "30 to <60"
+        else:
+            label = "60+"
+        histogram[label] += 1
+    return histogram

agent_hour_tracker/report.py

@@ -0,0 +1,82 @@
+"""Deterministic text and CSV renderers for agent-hour metrics."""
+
+from __future__ import annotations
+
+import csv
+import io
+
+from .metrics import ReportMetrics
+
+__all__ = ["render_csv", "render_share", "render_text"]
+
+
+def render_text(report: ReportMetrics) -> str:
+    """Render the summary, daily rows, and histogram as plain text."""
+
+    days = sorted(report.days, key=lambda day: day.date)
+    lines = [
+        "AGENT-HOUR SUMMARY",
+        f"Calendar days:{len(days):>16}",
+        f"Total agent-hours:{report.total_agent_hours:>12.2f}",
+        f"Mean / calendar day:{report.mean_per_calendar_day:>10.2f} h",
+        f"Mean / active day:{report.mean_per_active_day:>13.2f} h",
+        f"Median daily agent-hours:{report.median_agent_hours:>5.2f} h",
+        f"P95 daily agent-hours:{report.p95_agent_hours:>8.2f} h",
+        f"Maximum daily agent-hours:{report.max_agent_hours:>5.2f} h",
+        f"Active days:{report.active_days:>21}",
+        f"Zero days:{report.zero_days:>23}",
+        f"Days above 15 hours:{report.days_above_15_hours:>12}",
+        f"Days above 60 hours:{report.days_above_60_hours:>12}",
+        "",
+        "DAILY AGENT-HOURS",
+        f"{'Date':<28}{'Agent-hours':>5}{'Completed turns':>18}",
+    ]
+    lines.extend(
+        f"{day.date.isoformat():<28}{day.agent_hours:.2f}{day.completed_turns:>11}"
+        for day in days
+    )
+    lines.extend(("", "DAILY DISTRIBUTION"))
+    lines.extend(f"{label:<28}{count}" for label, count in report.histogram.items())
+    return "\n".join(lines) + "\n"
+
+
+def render_share(
+    report: ReportMetrics, tracker_version: str, methodology_version: str
+) -> str:
+    """Render a deterministic, conversation-free Archive Score card."""
+
+    days = sorted(report.days, key=lambda day: day.date)
+    if not days:
+        raise ValueError("share report requires at least one calendar day")
+    day_count = len(days)
+    completed_turns = sum(day.completed_turns for day in days)
+    lines = [
+        "CODEX AGENT-HOUR SCORE",
+        "",
+        f"{day_count} complete calendar days | "
+        f"{days[0].date.isoformat()} to {days[-1].date.isoformat()}",
+        "-" * 53,
+        f"Agent-hours/day: {report.mean_per_calendar_day:.2f}",
+        f"Total agent-hours: {report.total_agent_hours:.2f}",
+        f"Peak day: {report.max_agent_hours:.2f}",
+        f"Completed turns: {completed_turns}",
+        f"Active days: {report.active_days}/{day_count}",
+        "",
+        f"Archive Score | methodology v{methodology_version} | "
+        f"tracker v{tracker_version}",
+        "Calculated locally. No conversation content uploaded.",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def render_csv(report: ReportMetrics) -> str:
+    """Render one CSV row per calendar date with stable numeric precision."""
+
+    buffer = io.StringIO(newline="")
+    writer = csv.writer(buffer, lineterminator="\n")
+    writer.writerow(("date", "agent_hours", "completed_turns"))
+    for day in sorted(report.days, key=lambda day: day.date):
+        writer.writerow(
+            (day.date.isoformat(), f"{day.agent_hours:.6f}", day.completed_turns)
+        )
+    return buffer.getvalue()