stacktrace-cli 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
 # logged in any other process would reach Python's last-resort handler and

stacktrace_cli/analysis.py

@@ -62,6 +62,11 @@ class Analysis:
     #: is not yet countable and that only calls needing no composition are
     #: listed. `analyse` is always placed.
     placed: bool = True
+    #: `newest_hour` on `analyse_progressively`'s first preview, which reads
+    #: only the newest hour of the range; None for the whole range. A page
+    #: summing totals needs to tell the two apart, and `placed` cannot: both
+    #: previews are unplaced.
+    slice: str | None = None
 
 
 #: A count and an optional unit, anchored. Anchored rather than searched
@@ -451,6 +456,7 @@ def analyse_progressively(
     preview: timedelta | None = PREVIEW_WINDOW,
     cache: VerdictCache | None = None,
     attach_advisories: Any = None,
+    build_all: Any = None,
     analyzer: str = NO_ANALYZER,
     jev_key: str | None = None,
     history: DriftHistory | None = None,
@@ -463,6 +469,8 @@ def analyse_progressively(
     `history` is accepted and unused: this path never requests reasoning, so
     it never adds a point. It is here so the watcher can forward one options
     dict to both entry points (the test in `tests/monitor/test_watch.py`).
+    `build_all` is `analyse`'s own seam, forwarded for the same reason: the
+    offline monitor (`monitor/offline.py`) passes one that builds nothing.
 
     `analyse` answers once, which is right for a command that prints and exits
     and wrong for a page meant to look alive. Measured over 339 real sessions
@@ -510,7 +518,10 @@ def analyse_progressively(
         cutoff = window_end - preview
         # A window already narrower than the preview is read once, not twice.
         if cutoff > window_start:
-            yield _unplaced(read(cutoff), window_start=window_start, window_end=window_end)
+            yield replace(
+                _unplaced(read(cutoff), window_start=window_start, window_end=window_end),
+                slice="newest_hour",
+            )
 
     sessions = read(window_start)
     if preview is not None:
@@ -521,6 +532,7 @@ def analyse_progressively(
         bom_paths=bom_paths,
         project_map=project_map,
         attach_advisories=attach_advisories,
+        build_all=build_all,
     ).view
 
     def _stage(run: DetectorRun, sessions: tuple[CorrelatedSession, ...]) -> Analysis:

stacktrace_cli/cli.py

@@ -411,7 +411,9 @@ def detect(
     infrastructure change beyond what the user asked for are security; why
     the agent stopped, and who can unblock it, is reliability.
     The two families carry their own severity ladders, because a blocked agent
-    and a leaked credential cannot share one (ADR-0010).
+    and a leaked credential cannot share one (ADR-0010). Cost findings are the
+    daemon's, which judges a whole day and a 30-day baseline (ADR-0097);
+    `stacktrace findings` shows them.
 
     Both stages read the record on this machine. Neither needs a model, a
     credential or an account, and on a default run nothing derived from a

stacktrace_cli/cost/__init__.py

@@ -0,0 +1,6 @@
+"""What agent work uses, in tokens, and how far above the usual (ADR-0099).
+
+Pure functions over the session shape (`sessions/protocols.py`). Nothing here
+reads a file, a clock or the store; hosts pass those in. Nothing here prices:
+every figure is tokens, or a ratio to the usual.
+"""

stacktrace_cli/cost/baseline.py

@@ -0,0 +1,493 @@
+"""The environment's baseline: what this developer's work usually looks like.
+
+Two halves (ADR-0093):
+
+- **`summarize(run)`** turns one finished run into one row of numbers: its
+  tokens by active minute, its 5-minute burn, its behaviour measures, and its
+  tokens by model and quarter hour of the day. Numbers only, never content. The
+  daemon stores one row per finished main session (`cost_baselines`).
+- **`snapshot(rows, ...)`** turns 30 days of rows into the percentiles the
+  rules compare against, by cohort `(repo, entrypoint, model)`, widening to
+  `(entrypoint, model)` and then `(model)` below 20 sessions. Frozen for each
+  evaluation, so a rule's output never depends on when it was read.
+
+Tokens, never dollars, and recorded tokens only: nothing else ever
+enters a baseline.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, time, timedelta, tzinfo
+from statistics import median
+from typing import Any, TypeVar
+
+from stacktrace_cli.cost.measures import (
+    active_minutes,
+    cache_rewrites,
+    calls_in_order,
+    context_tokens,
+    cumulative_by_active_minute,
+    fresh_by_design,
+    minute_burn,
+    most_started_within,
+    recorded_tokens,
+    repeats,
+    tokens_by_slot,
+)
+from stacktrace_cli.cost.models import canonical_model
+from stacktrace_cli.cost.runs import Run
+from stacktrace_cli.cost.tokens import Tokens
+from stacktrace_cli.sessions.protocols import ModelResponseLike, SessionLike
+
+#: A run's curves are kept to this many active minutes.
+MAX_MINUTES = 240
+#: The fewest sessions a cohort level needs before a rule may use it.
+MIN_SESSIONS = 20
+#: The fewest working days the day curve needs.
+MIN_WORKING_DAYS = 10
+#: A context counts as large above this many tokens (cache-collapse).
+LARGE_CONTEXT = 50_000
+#: How long since a run's last response before it counts as finished.
+FINISHED_AFTER = timedelta(hours=1)
+#: How far back the baseline reaches.
+WINDOW = timedelta(days=30)
+
+
+def baseline_since(now: datetime, zone: tzinfo | None) -> datetime:
+    """Where the baseline's window begins: the start of the local day 30 days
+    before today. A run is in the window while its last response's local date
+    is, so the window, and every baseline built from it, moves only at
+    midnight (cost-phase-1 §1, "Finished run"). In UTC, as the store keeps
+    times."""
+    zone = zone or UTC
+    first = now.astimezone(zone).date() - timedelta(days=WINDOW.days)
+    return datetime.combine(first, time.min, tzinfo=zone).astimezone(UTC)
+
+
+Cohort = tuple[str | None, str | None, str | None]
+#: Sorts an undated response first; only ever a sort key.
+_NEVER = datetime.min.replace(tzinfo=UTC)
+
+
+@dataclass(frozen=True)
+class Summary:
+    """One finished run, as numbers."""
+
+    run_id: str
+    agent_kind: str | None
+    cohort: Cohort
+    day: date
+    last_activity_at: datetime
+    #: Recorded tokens by the end of each active minute.
+    curve: tuple[int, ...]
+    #: Recorded tokens in the 5 minutes ending at each active minute.
+    burn: tuple[int, ...]
+    tokens: int
+    subagents_in_10m: int
+    repeats: int
+    input_per_response: int
+    #: The lowest cache-read share over 5 responses running on a large
+    #: context; None when the run never had 5 in a row, so it says nothing
+    #: about the cache and stays out of the cohort's percentiles.
+    lowest_cache_share: float | None
+    cache_rewrites: int
+    #: Recorded tokens by `date|model|quarter-hour`, each response on its own
+    #: local date; read through `dated_slots`.
+    slots: Mapping[str, int] = field(default_factory=dict)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "curve": list(self.curve),
+            "burn": list(self.burn),
+            "tokens": self.tokens,
+            "subagents_in_10m": self.subagents_in_10m,
+            "repeats": self.repeats,
+            "input_per_response": self.input_per_response,
+            "lowest_cache_share": self.lowest_cache_share,
+            "cache_rewrites": self.cache_rewrites,
+            "slots": dict(self.slots),
+        }
+
+    @classmethod
+    def from_row(
+        cls,
+        *,
+        run_id: str,
+        agent_kind: str | None,
+        cohort: Cohort,
+        day: date,
+        last_activity_at: datetime,
+        summary: Mapping[str, Any],
+    ) -> Summary:
+        return cls(
+            run_id=run_id,
+            agent_kind=agent_kind,
+            cohort=cohort,
+            day=day,
+            last_activity_at=last_activity_at,
+            curve=tuple(int(x) for x in summary.get("curve", ())),
+            burn=tuple(int(x) for x in summary.get("burn", ())),
+            tokens=int(summary.get("tokens", 0)),
+            subagents_in_10m=int(summary.get("subagents_in_10m", 0)),
+            repeats=int(summary.get("repeats", 0)),
+            input_per_response=int(summary.get("input_per_response", 0)),
+            lowest_cache_share=(
+                None
+                if summary.get("lowest_cache_share") is None
+                else float(summary["lowest_cache_share"])
+            ),
+            cache_rewrites=int(summary.get("cache_rewrites", 0)),
+            slots={str(k): int(v) for k, v in dict(summary.get("slots", {})).items()},
+        )
+
+
+def is_finished(run: Run[Any], now: datetime) -> bool:
+    """Whether nothing has been recorded in the run for an hour: no response
+    and no turn. A new prompt resumes a run before any reply to it, so a run
+    the baseline holds leaves it from that prompt on (cost-phase-1 §1,
+    "Finished run")."""
+    moments = [
+        moment
+        for session in run.sessions
+        for moment in (
+            *(r.occurred_at for r in session.responses),
+            *(t.occurred_at for t in getattr(session, "turns", ())),
+        )
+        if moment is not None
+    ]
+    return bool(moments) and now - max(moments) >= FINISHED_AFTER
+
+
+L = TypeVar("L", bound=SessionLike)
+
+
+def summarize(run: Run[L], zone: tzinfo) -> Summary | None:
+    """A run as one row of numbers, or None for a run with no main session or
+    no dated response."""
+    main = run.main
+    responses = _responses(run)
+    last = _last_activity(run)
+    if main is None or not responses or last is None:
+        return None
+    # A session is judged together with its sub-agents, so its curve counts
+    # theirs: a fan-out of small sub-agents is how a session spends fast.
+    curve = cumulative_by_active_minute(responses)[:MAX_MINUTES]
+    minutes = active_minutes(responses)[:MAX_MINUTES]
+    burn = tuple(minute_burn(responses, minute) for minute in minutes)
+    found = repeats(calls_in_order(run.sessions))
+    slots = {
+        f"{day.isoformat()}|{model}|{slot}": tokens
+        for (day, model, slot), tokens in tokens_by_slot(responses, zone).items()
+    }
+    return Summary(
+        run_id=run.run_id,
+        agent_kind=run.agent_kind,
+        cohort=cohort_of(run),
+        day=last.astimezone(zone).date(),
+        last_activity_at=last,
+        curve=curve,
+        burn=burn,
+        tokens=sum(recorded_tokens(r) for r in responses),
+        subagents_in_10m=most_started_within(
+            (s.started_at for s in run.subagents), timedelta(minutes=10)
+        ),
+        repeats=found[0].repeats if found else 0,
+        input_per_response=_p90([context_tokens(r) for r in responses]),
+        lowest_cache_share=lowest_cache_share(main),
+        cache_rewrites=len(rewrites_on_a_large_context(run.sessions)),
+        slots=slots,
+    )
+
+
+def cohort_of(run: Run[Any]) -> Cohort:
+    """`(repo, entrypoint, model)`: the main session's working directory and
+    how it was driven, and the model that carried most of the run's tokens,
+    its sub-agents' included. A run's figures are the whole run's, so its
+    model is too: one whose sub-agents ran mostly on another model is judged
+    against that model's history, not its main session's."""
+    by_model: dict[str | None, int] = {}
+    for session in run.sessions:
+        for response in session.responses:
+            # A response without a time counts nowhere, the cohort included
+            # (§1). One without a model counts toward an unknown model, so its
+            # tokens are not handed to whichever model was named.
+            if response.occurred_at is not None:
+                key = canonical_model(response.model) if response.model else None
+                by_model[key] = by_model.get(key, 0) + recorded_tokens(response)
+    model = max(by_model, key=lambda m: by_model[m]) if by_model else None
+    main = run.main or run.sessions[0]
+    return (main.working_directory, main.entrypoint, model)
+
+
+def rewrites_on_a_large_context(
+    sessions: Iterable[SessionLike],
+) -> list[ModelResponseLike]:
+    """Cache re-writes on a context over `LARGE_CONTEXT`, in every session:
+    what `cache-collapse` counts, and so what its baseline counts."""
+    found = [r for s in sessions for r in cache_rewrites(s) if context_tokens(r) > LARGE_CONTEXT]
+    # In time order across the sessions, so "the third re-write" is the third
+    # made, not the third listed (cost-phase-1 §1).
+    return sorted(found, key=lambda r: r.occurred_at or _NEVER)
+
+
+def _streaks(session: SessionLike, run_of: int) -> Iterator[tuple[float, ModelResponseLike]]:
+    """Each `run_of` responses in a row on a large context: the highest
+    cache-read share among them, and the response that ends them. A response
+    that starts its cache afresh by design ends a streak rather than joining
+    it: it had no cache to read, which is no evidence of one going unused."""
+    shares: list[float] = []
+    for response, fresh in fresh_by_design(session):
+        context = context_tokens(response)
+        if context <= LARGE_CONTEXT or fresh:
+            shares = []
+            continue
+        shares.append(Tokens.of(response.usage).cache_read / context)
+        if len(shares) >= run_of:
+            yield max(shares[-run_of:]), response
+
+
+def lowest_cache_share(session: SessionLike, run_of: int = 5) -> float | None:
+    """The lowest cache-read share over `run_of` responses in a row, each on a
+    large context; None when there were never that many in a row."""
+    return min((share for share, _end in _streaks(session, run_of)), default=None)
+
+
+def lowest_streak_end(session: SessionLike, run_of: int = 5) -> ModelResponseLike | None:
+    """The response that ended the run of `run_of` with the lowest cache-read
+    share: what a cache-collapse finding states, and where it happened."""
+    found = list(_streaks(session, run_of))
+    return min(found, key=lambda pair: pair[0])[1] if found else None
+
+
+# The snapshot.
+
+
+@dataclass(frozen=True)
+class Bars:
+    """One cohort's percentiles, with how many runs they came from."""
+
+    n: int
+    level: str
+    p5: Mapping[str, float]
+    p50: Mapping[str, float]
+    p95: Mapping[str, float]
+    p99: Mapping[str, float]
+    #: Per active minute: (p50, p95, p99) of cumulative tokens and of burn.
+    curve: tuple[tuple[float, float, float], ...]
+    burn: tuple[tuple[float, float, float], ...]
+
+
+@dataclass(frozen=True)
+class DayCurve:
+    """One model's usual tokens by each quarter hour, over its working days."""
+
+    days: int
+    #: Cumulative recorded tokens by slot on each working day.
+    by_day: Mapping[date, tuple[int, ...]]
+    #: Cumulative recorded tokens by slot, on each working day.
+    usual: tuple[float, ...]
+    #: The spread of log(day ÷ usual) at each slot: 1.48 × MAD, at least 0.25.
+    spread: tuple[float, ...]
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    built_at: datetime
+    runs: int
+    by_cohort: Mapping[Cohort, Bars]
+    by_entrypoint_model: Mapping[tuple[str | None, str | None], Bars]
+    by_model: Mapping[str | None, Bars]
+    days: Mapping[str, DayCurve]
+
+    def bars(self, cohort: Cohort) -> Bars | None:
+        """The narrowest level with enough runs, or None: the rule is silent."""
+        repo, entrypoint, model = cohort
+        for found in (
+            self.by_cohort.get((repo, entrypoint, model)),
+            self.by_entrypoint_model.get((entrypoint, model)),
+            self.by_model.get(model),
+        ):
+            if found is not None and found.n >= MIN_SESSIONS:
+                return found
+        return None
+
+
+_MEASURES = (
+    "tokens",
+    "subagents_in_10m",
+    "repeats",
+    "input_per_response",
+    "lowest_cache_share",
+    "cache_rewrites",
+)
+
+
+def snapshot(
+    summaries: Iterable[Summary],
+    *,
+    flagged: frozenset[tuple[str, str]] = frozenset(),
+    now: datetime,
+    zone: tzinfo | None = None,
+) -> Snapshot:
+    """The baseline as of `now`: the last 30 days of runs, without the runs a
+    cost finding was raised on (ADR-0093). The day curve leaves out today,
+    which is what it is compared with.
+
+    `flagged` holds `(agent_kind, run_id)` pairs: a run id is unique only
+    within the reader that emitted it."""
+    recent = [s for s in summaries if s.last_activity_at >= baseline_since(now, zone)]
+    kept = [s for s in recent if (s.agent_kind, s.run_id) not in flagged]
+    today = now.astimezone(zone).date() if zone is not None else now.date()
+    by_cohort: dict[Cohort, list[Summary]] = {}
+    by_entrypoint_model: dict[tuple[str | None, str | None], list[Summary]] = {}
+    by_model: dict[str | None, list[Summary]] = {}
+    for summary in kept:
+        _repo, entrypoint, model = summary.cohort
+        by_cohort.setdefault(summary.cohort, []).append(summary)
+        by_entrypoint_model.setdefault((entrypoint, model), []).append(summary)
+        by_model.setdefault(model, []).append(summary)
+    return Snapshot(
+        built_at=now,
+        runs=len(kept),
+        by_cohort={k: _bars(v, "repo, entrypoint and model") for k, v in by_cohort.items()},
+        by_entrypoint_model={
+            k: _bars(v, "entrypoint and model") for k, v in by_entrypoint_model.items()
+        },
+        by_model={k: _bars(v, "model") for k, v in by_model.items()},
+        days=_day_curves(kept, before=today),
+    )
+
+
+def _bars(summaries: Sequence[Summary], level: str) -> Bars:
+    # A measure a run has no value for (a cache share without a five-response
+    # streak) stays out of the percentiles rather than counting as perfect.
+    columns = {
+        name: [float(v) for s in summaries if (v := getattr(s, name)) is not None]
+        for name in _MEASURES
+    }
+    return Bars(
+        n=len(summaries),
+        level=level,
+        p5={k: _quantile(v, 0.05) for k, v in columns.items()},
+        p50={k: _quantile(v, 0.5) for k, v in columns.items()},
+        p95={k: _quantile(v, 0.95) for k, v in columns.items()},
+        p99={k: _quantile(v, 0.99) for k, v in columns.items()},
+        curve=_by_minute([s.curve for s in summaries]),
+        burn=_by_minute([s.burn for s in summaries]),
+    )
+
+
+def _by_minute(curves: Sequence[Sequence[int]]) -> tuple[tuple[float, float, float], ...]:
+    """At each active minute, p50, p95 and p99 over the runs that reached it."""
+    longest = max((len(c) for c in curves), default=0)
+    rows: list[tuple[float, float, float]] = []
+    for minute in range(longest):
+        values = [float(c[minute]) for c in curves if len(c) > minute]
+        rows.append((_quantile(values, 0.5), _quantile(values, 0.95), _quantile(values, 0.99)))
+    return tuple(rows)
+
+
+def dated_slots(summary: Summary) -> Iterator[tuple[date, str, int, int]]:
+    """A summary's slots as `(date, model, quarter hour, tokens)`.
+
+    A key is `date|model|slot`; a row written before slots carried their date
+    is `model|slot`, on its run's day. The model is recorded text and may hold
+    a `|`, so the date is split off the front and the slot off the back.
+    """
+    for key, tokens in summary.slots.items():
+        head, _, rest = key.partition("|")
+        try:
+            on = date.fromisoformat(head)
+        except ValueError:
+            on, rest = summary.day, key
+        model, _, slot = rest.rpartition("|")
+        yield on, model, int(slot), tokens
+
+
+def _in_window(on: date, before: date) -> bool:
+    """A date the day curve and the usual read: one of the 30 days before
+    `before`. A run counts by its last response, but a long-resumed run's
+    older days are outside the window and count nowhere (cost-phase-1 §1)."""
+    return before - timedelta(days=WINDOW.days) <= on < before
+
+
+def tokens_by_working_day(summaries: Iterable[Summary], *, before: date) -> dict[date, int]:
+    """Recorded tokens on each working day of the 30 before `before`, on every
+    model: the days the day curve reads (cost-phase-1 §1, "The clock")."""
+    days: dict[date, int] = {}
+    for summary in summaries:
+        for on, _model, _slot, tokens in dated_slots(summary):
+            if _in_window(on, before):
+                days[on] = days.get(on, 0) + tokens
+    return days
+
+
+def _by_model_day(summaries: Iterable[Summary], before: date) -> dict[str, dict[date, list[int]]]:
+    by_model_day: dict[str, dict[date, list[int]]] = {}
+    for summary in summaries:
+        for on, model, slot, tokens in dated_slots(summary):
+            if not _in_window(on, before):
+                continue
+            days = by_model_day.setdefault(model, {})
+            day = days.setdefault(on, [0] * 96)
+            day[slot] += tokens
+    return by_model_day
+
+
+def _day_curves(summaries: Sequence[Summary], *, before: date) -> dict[str, DayCurve]:
+    """Per model, cumulative tokens by quarter hour on each working day (a day
+    with any recorded response) of the 30 before `before`, its median, and the
+    spread ADR-0093 scores by. Each slot counts on its own date, so a run across
+    midnight adds to both days rather than all to its last."""
+    by_model_day = _by_model_day(summaries, before)
+    curves: dict[str, DayCurve] = {}
+    for model, days in by_model_day.items():
+        cumulative = [_accumulate(slots) for slots in days.values()]
+        usual = tuple(median(day[s] for day in cumulative) for s in range(96))
+        spread = []
+        for s in range(96):
+            logs = [math.log((day[s] + 1) / (usual[s] + 1)) for day in cumulative]
+            centre = median(logs)
+            mad = median(abs(x - centre) for x in logs)
+            spread.append(max(1.48 * mad, 0.25))
+        curves[model] = DayCurve(
+            days=len(cumulative),
+            by_day={day: tuple(_accumulate(slots)) for day, slots in days.items()},
+            usual=usual,
+            spread=tuple(spread),
+        )
+    return curves
+
+
+def _accumulate(slots: Sequence[int]) -> list[int]:
+    total, out = 0, []
+    for value in slots:
+        total += value
+        out.append(total)
+    return out
+
+
+def _quantile(values: Sequence[float], share: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    position = share * (len(ordered) - 1)
+    low = math.floor(position)
+    high = math.ceil(position)
+    return ordered[low] + (ordered[high] - ordered[low]) * (position - low)
+
+
+def _p90(values: Sequence[int]) -> int:
+    return int(_quantile([float(v) for v in values], 0.9)) if values else 0
+
+
+def _responses(run: Run[Any]) -> list[ModelResponseLike]:
+    return [r for s in run.sessions for r in s.responses if r.occurred_at is not None]
+
+
+def _last_activity(run: Run[Any]) -> datetime | None:
+    times = [r.occurred_at for r in _responses(run) if r.occurred_at is not None]
+    return max(times) if times else None

stacktrace_cli/cost/clock.py

@@ -0,0 +1,40 @@
+"""The environment's time zone, which every local day, quarter hour and
+window of cost is in (cost-phase-1 §1, "The clock")."""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+_LOCALTIME = "/etc/localtime"
+
+
+def environment_zone() -> tzinfo:
+    """The environment's time zone, with its daylight-saving rules: the zone
+    `TZ` names, else the one `/etc/localtime` links to.
+
+    Each response is placed in the local day and quarter hour of its own
+    moment. The offset in effect today would place every response from before
+    a clock change an hour off, and some near midnight on the wrong date. Only
+    when neither names a zone this release can load is the current offset
+    used, and then a clock change moves history by an hour.
+    """
+    for name in (os.environ.get("TZ"), _linked()):
+        if not name:
+            continue
+        try:
+            return ZoneInfo(name.removeprefix(":"))
+        except (ZoneInfoNotFoundError, ValueError):
+            continue
+    return datetime.now().astimezone().tzinfo or UTC
+
+
+def _linked() -> str | None:
+    """The zone `/etc/localtime` links to, by its name in the zone database."""
+    try:
+        target = os.readlink(_LOCALTIME)
+    except OSError:
+        return None
+    _, marker, name = target.partition("zoneinfo/")
+    return name if marker else None