steam-backlog-enforcer/steam_backlog_enforcer/_playtime_engagement.py
Krzysztof kuhy Rudnicki 1faf211767 Show which games make up the gaming budget, and bill osu!lazer
The budget tab answered "how much did I play" but not "what did I play":
playtime_state.json and playtime_history.json each stored one aggregate
seconds figure per gaming day, so the 14-day chart was a row of featureless
bars. Separately, qualifying_pids had exactly two sources — the SteamAppId
env var and a hardcoded 16-launcher frozenset — so osu!lazer, which sets no
SteamAppId and matches no launcher name, was never billed at all.

qualifying_pids now returns pid -> attribution key instead of a bare pid set.
The app id was already in hand and thrown away on its first line; it now
survives into PlaytimeState.per_game, alongside a user-editable
counted_processes list in config.json seeded with osu!lazer.

Two things the parts/whole relationship forces:

  - per_game only ever sums to AT MOST seconds, never equals it. backdate
    refunds the idle grace on every engaged-to-paused edge, and
    _state_or_recover synthesises a full budget with no breakdown. The
    refund is debited from last_credited_key, and the remainder is rendered
    as "Unattributed" rather than stored — one path then covers legacy days,
    focus-probe failures and drift alike.

  - counted_processes is kept apart from LAUNCHER_PROCESS_NAMES. That
    frozenset is also the total-block kill list, and it routes through
    kill_and_uninstall_launchers, which pacman -R's the owning package.
    Counted entries are killed on total block, never uninstalled.

Both storage formats stay at schema 1: load_state already filters to
dataclass fields, so a record without per_game migrates for free, and the
history reader has to accept both a bare float and an object regardless, so
a version bump would distinguish nothing.

Chart segments use the shared design system's categorical ramp (--cat-1..6),
capped at six games plus "Other" because a seventh distinguishable hue does
not exist under simulated CVD. The red over-budget fill is gone: colour now
encodes which game, and the dashed budget line alone says over or under.

Snapshot persistence moves to _snapshot.py to keep config.py under the
250-line cap. Three modules bound config paths at import time, which
bypasses the conftest redirect — they now reach them through the module.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MKFzwzwRU1JD7SFLHtQBsz
2026-08-29 18:32:03 +02:00

173 lines
6.0 KiB
Python

"""Deciding whether the user is actually playing, not just leaving a game open.
A running game process is not evidence of play. The budget was previously billed
for two hours during which a screen locker covered the display and the machine
could not be touched at all — the game was simply still resident.
Three signals gate a tick, evaluated together rather than short-circuited, so
that the log can answer "was the screen *also* locked?" after the fact and the
backdate can tell an idle-only pause from a compound one. The probes themselves
live in :mod:`_engagement_probes`.
This module owns the per-tick verdict and the one piece of state a pure function
cannot hold: the previous verdict, which the idle backdate needs to recognise an
engaged-to-paused edge.
"""
from __future__ import annotations
from dataclasses import replace
import logging
from typing import TYPE_CHECKING
from steam_backlog_enforcer._controller_input import ControllerActivity
from steam_backlog_enforcer._engagement_probes import (
assess_focus,
assess_idle,
assess_screen,
)
from steam_backlog_enforcer._engagement_types import (
STATE_ENGAGED,
STATE_NOT_APPLICABLE,
STATE_PAUSED,
CauseTally,
EngagementVerdict,
)
from steam_backlog_enforcer._screen_hold import holder_lock_path
from steam_backlog_enforcer._x_probe import XProbe
if TYPE_CHECKING:
from pathlib import Path
from steam_backlog_enforcer._playtime_state import PlaytimeRules, PlaytimeState
logger = logging.getLogger(__name__)
class EngagementTracker:
"""Assesses engagement per tick and owns the state the backdate needs."""
def __init__(
self,
*,
uid: int,
probe: XProbe | None = None,
controller: ControllerActivity | None = None,
holder_path: Path | None = None,
) -> None:
"""Build a tracker over the desktop session owned by *uid*.
Args:
uid: Owner of the desktop session.
probe: X probe, injected by tests.
controller: Controller-activity watcher, injected by tests.
holder_path: gatelock holder lock, injected by tests.
"""
self._probe = probe if probe is not None else XProbe()
self._controller = (
controller if controller is not None else ControllerActivity()
)
self._holder_path = (
holder_path if holder_path is not None else holder_lock_path(uid)
)
self._previous: EngagementVerdict | None = None
self._previous_day: str | None = None
def close(self) -> None:
"""Release the X connection and controller devices."""
self._probe.close()
self._controller.close()
def assess(
self,
rules: PlaytimeRules,
*,
qualifying: set[int],
now_monotonic: float,
) -> EngagementVerdict:
"""Judge whether this tick counts against the budget.
Args:
rules: Policy for this tick.
qualifying: PIDs that would otherwise count.
now_monotonic: Monotonic timestamp, for controller-activity ages.
Returns:
The verdict for this tick.
"""
if not qualifying:
return EngagementVerdict(state=STATE_NOT_APPLICABLE)
pids = tuple(sorted(qualifying))
if not rules.engagement_gate:
return EngagementVerdict(state=STATE_ENGAGED, qualifying=pids)
tally = CauseTally()
held, holder_pid = assess_screen(self._holder_path, tally)
focus_pid = assess_focus(self._probe, rules, qualifying, tally)
idle, controller_idle = assess_idle(
self._probe, self._controller, rules, tally, now_monotonic
)
return EngagementVerdict(
state=STATE_PAUSED if tally.causes else STATE_ENGAGED,
causes=tuple(tally.causes),
degraded=tuple(tally.degraded),
idle_seconds=idle,
controller_idle_seconds=controller_idle,
screen_held=held,
holder_pid=holder_pid,
focus_pid=focus_pid,
qualifying=pids,
)
def backdate(
self,
state: PlaytimeState,
verdict: EngagementVerdict,
*,
rules: PlaytimeRules,
) -> PlaytimeState:
"""Refund the idle grace period once per walk-away.
Time billed *before* the idle threshold tripped was not play either, so
the first paused tick of an idle-only spell gives it back. Deliberately
conservative: it fires only on the engaged-to-paused edge, only when
idleness is the sole cause, and never across a day rollover — and after
a daemon restart there is no previous verdict, so nothing is refunded.
Args:
state: Accounting state after this tick's accumulation.
verdict: This tick's verdict.
rules: Policy for this tick.
Returns:
The state, with the grace period deducted when all of that holds.
"""
previous, previous_day = self._previous, self._previous_day
self._previous, self._previous_day = verdict, state.day_key
if previous is None or previous.state != STATE_ENGAGED:
return state
if previous_day != state.day_key:
return state
if not verdict.idle_only():
return state
refunded = max(0.0, state.seconds - rules.idle_grace_seconds)
amount = state.seconds - refunded
logger.info(
"Idle for %.0fs; refunding the %.0fs grace period.",
verdict.idle_seconds or 0.0,
amount,
)
# The refund must come off the same key it was billed to, or the
# per-game parts drift above the whole on every walk-away — which is
# many times a day, and would render as segments overflowing the bar.
per_game = dict(state.per_game)
key = state.last_credited_key
if key and key in per_game:
per_game[key] = max(0.0, per_game[key] - amount)
return replace(state, seconds=refunded, per_game=per_game)