stacktrace-cli 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.1"

stacktrace_cli/analysis.py

@@ -19,19 +19,22 @@ path's tests already pin.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Iterator
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
-from typing import Any
+from typing import Any, Final
 
 from stacktrace_cli.correlate.orchestrate import Acquired, acquire_correlated_view
 from stacktrace_cli.correlate.project_map import parse_mapping
 from stacktrace_cli.correlate.record import CorrelatedSession, CorrelatedView, Coverage
 from stacktrace_cli.detector.cache import VerdictCache
+from stacktrace_cli.detector.history import DriftHistory
 from stacktrace_cli.detector.run import (
     DEFAULT_BUDGET,
     DEFAULT_SAMPLE_BUDGET,
+    NO_ANALYZER,
     DetectorRun,
     run_detector,
 )
@@ -61,41 +64,91 @@ class Analysis:
     placed: bool = True
 
 
+#: A count and an optional unit, anchored. Anchored rather than searched
+#: because the tolerance this parser owes the upload path is about the *unit*
+#: being omissible, not about the value being loosely shaped: `int` alone would
+#: read `'5 m'` as five (it strips whitespace before parsing) and a signed
+#: `'-1h'` as a negative window, so the shape is pinned here and the count is
+#: parsed from digits already known to be digits.
+_SINCE_SPELLING: Final = re.compile(r"^(\d+)([mhd]?)$")
+
+#: The unit suffixes, and the `timedelta` keyword each one names. The empty
+#: key is the bare count -- `'7'`, which the upload path's config value has
+#: always spelled without a unit and which has always meant days.
+_SINCE_UNITS: Final = {"m": "minutes", "h": "hours", "d": "days", "": "days"}
+
+#: One message for every way the spelling can be wrong, because they are one
+#: user mistake: a window that does not name a positive amount of time. Shared
+#: with `cli.py`'s stricter parser so a reader meets the same vocabulary
+#: whichever of the two refused them.
+SINCE_HINT: Final = "like '5m', '2h' or '7d'"
+
+
 def parse_since(value: str) -> datetime:
-    """`7d` or `7` -> an aware UTC cut-off.
+    """`5m`, `2h`, `7d` or `7` -> an aware UTC cut-off.
+
+    Sub-day units are here rather than only at the command line because the
+    window reaches this module as a *string* from every caller that has one --
+    `monitor` hands it over untouched and parses it on the watcher thread, so a
+    unit the command line accepted and this parser did not would raise where no
+    request is left to answer.
 
     Raises `ValueError`, never a Click or transport exception: this module is
     below both. The message is the upload path's, which its tests pin.
     """
-    text = value.strip().lower()
+    match = _SINCE_SPELLING.match(value.strip().lower())
+    if not match:
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}")
     try:
-        days = int(text[:-1]) if text.endswith("d") else int(text)
+        count = int(match.group(1))
     except ValueError:
-        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
-    if days <= 0:
-        raise ValueError(f"--since must be a positive day count, not {value!r}")
+        # `int` refuses a string past its default digit-conversion limit. The
+        # same user mistake as a non-numeric value, so the same diagnostic.
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}") from None
+    if count <= 0:
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}")
     try:
-        return datetime.now(UTC) - timedelta(days=days)
+        return datetime.now(UTC) - timedelta(**{_SINCE_UNITS[match.group(2)]: count})
     except OverflowError:
         # `timedelta` takes any `int` but overflows past `timedelta.max.days`.
         # The same user mistake as a non-numeric value, so the same diagnostic.
-        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
+        raise ValueError(f"--since must be a positive window {SINCE_HINT}, not {value!r}") from None
 
 
-def _only(view: SessionView, session_ids: tuple[str, ...]) -> SessionView:
-    """The window narrowed to named sessions, or the window itself.
+def _only(
+    view: SessionView,
+    session_ids: tuple[str, ...],
+    agent_kinds: tuple[str, ...],
+) -> SessionView:
+    """The window narrowed to named session identities, or the window itself.
 
     Narrowed *before* correlation rather than after judgement, because the point
     is that nothing else can be dispatched: a caller that pays for one named
     session must not be able to spend that payment on another one the detector
-    happened to rank higher. `unavailable` is carried through unchanged — a
-    reader that failed is still a reader that failed, whichever session was
-    asked for.
+    happened to rank higher. The kind and id filters are both applied when the
+    caller supplies both halves of the identity. `unavailable` is carried
+    through unchanged — a reader that failed is still a reader that failed,
+    whichever session was asked for.
+
+    A kind-anonymous session (`agent_kind is None`) is never dropped by the
+    kind filter: `sessions/access.py`'s coverage contract is that a session
+    OpenAIDR could not map to a kind is a gap to surface, not a kind the user
+    filtered out, and this seam must not reintroduce that drop after
+    collection already kept it.
     """
-    if not session_ids:
+    if not session_ids and not agent_kinds:
         return view
     wanted = set(session_ids)
-    return replace(view, sessions=tuple(s for s in view.sessions if s.session_id in wanted))
+    kinds = set(agent_kinds)
+    return replace(
+        view,
+        sessions=tuple(
+            session
+            for session in view.sessions
+            if (not wanted or session.session_id in wanted)
+            and (not kinds or session.agent_kind is None or session.agent_kind in kinds)
+        ),
+    )
 
 
 def analyse(
@@ -111,6 +164,10 @@ def analyse(
     sample_budget: int = DEFAULT_SAMPLE_BUDGET,
     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,
 ) -> Analysis:
     """Read this machine's sessions, correlate them, and judge them.
 
@@ -122,23 +179,111 @@ def analyse(
     cache through it so osv.dev is asked once per component rather than once per
     pass; a one-shot command passes nothing and gets the default.
 
+    `build_all` is the same kind of seam for composition builds, which shell out
+    and cost seconds each. A long-lived process passes a cache through it so an
+    unchanged machine or project is not rebuilt on every pass; a one-shot
+    command passes nothing and gets the default.
+
     `session_ids` narrows the window to named sessions. Empty means the whole
     window, which is what every command passes; monitor's reasoning button is
     what needs the narrowing, and needs it to be structural.
 
     `since` is the window's spelling — `parse_since` reads it — or the cutoff
     itself, for a caller whose own `--since` spelling is not this one's.
+
+    `reasoning` switches the third stage on and is off by default; `jev_key`
+    hands the analyzer a key a caller already holds, in place of reading
+    `TYPESAFE_API_KEY`. Both travel to `run_detector` unchanged, so a
+    programmatic caller controls exactly what `detect` controls.
     """
     window_end = datetime.now(UTC)
     window_start = since if isinstance(since, datetime) else parse_since(since)
-    acquired = _correlated(
+    sessions = _collected(
         agent_kinds=agent_kinds,
         window_start=window_start,
-        bom_paths=bom_paths,
-        project_map=project_map,
         root=root,
         session_ids=session_ids,
+    )
+    return _analyse_sessions(
+        sessions,
+        window_start=window_start,
+        window_end=window_end,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        reasoning=reasoning,
+        budget=budget,
+        sample_budget=sample_budget,
+        cache=cache,
         attach_advisories=attach_advisories,
+        build_all=build_all,
+        analyzer=analyzer,
+        jev_key=jev_key,
+        history=history,
+    )
+
+
+def analyse_sessions(
+    sessions: SessionView,
+    *,
+    agent_kinds: tuple[str, ...] = (),
+    since: str | datetime = "7d",
+    bom_paths: tuple[Path, ...] = (),
+    project_map: tuple[str, ...] = (),
+    session_ids: tuple[str, ...] = (),
+    reasoning: bool = False,
+    budget: int = DEFAULT_BUDGET,
+    sample_budget: int = DEFAULT_SAMPLE_BUDGET,
+    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,
+) -> Analysis:
+    """Correlate and judge a session view already collected by a long-lived reader."""
+    window_end = datetime.now(UTC)
+    window_start = since if isinstance(since, datetime) else parse_since(since)
+    return _analyse_sessions(
+        _only(sessions, session_ids, agent_kinds),
+        window_start=window_start,
+        window_end=window_end,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        reasoning=reasoning,
+        budget=budget,
+        sample_budget=sample_budget,
+        cache=cache,
+        attach_advisories=attach_advisories,
+        build_all=build_all,
+        analyzer=analyzer,
+        jev_key=jev_key,
+        history=history,
+    )
+
+
+def _analyse_sessions(
+    sessions: SessionView,
+    *,
+    window_start: datetime,
+    window_end: datetime,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    reasoning: bool,
+    budget: int,
+    sample_budget: int,
+    cache: VerdictCache | None,
+    attach_advisories: Any,
+    build_all: Any,
+    analyzer: str,
+    jev_key: str | None,
+    history: DriftHistory | None,
+) -> Analysis:
+    acquired = _acquire(
+        sessions,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        attach_advisories=attach_advisories,
+        build_all=build_all,
     )
     run = run_detector(
         acquired.view,
@@ -146,6 +291,9 @@ def analyse(
         budget=budget,
         sample_budget=sample_budget,
         cache=cache,
+        analyzer=analyzer,
+        jev_key=jev_key,
+        history=history,
     )
     return Analysis(
         run=run,
@@ -170,7 +318,11 @@ def _collected(
     session_ids: tuple[str, ...],
 ) -> SessionView:
     """Read the window. Its own function so a caller can read twice."""
-    return _only(collect_sessions(list(agent_kinds) or None, window_start, root=root), session_ids)
+    return _only(
+        collect_sessions(list(agent_kinds) or None, window_start, root=root),
+        session_ids,
+        agent_kinds,
+    )
 
 
 def _acquire(
@@ -179,9 +331,14 @@ def _acquire(
     bom_paths: tuple[Path, ...],
     project_map: tuple[str, ...],
     attach_advisories: Any,
+    build_all: Any = None,
 ) -> Acquired:
     """Correlate what was read."""
-    hook = {} if attach_advisories is None else {"attach_advisories": attach_advisories}
+    hook: dict[str, Any] = {}
+    if attach_advisories is not None:
+        hook["attach_advisories"] = attach_advisories
+    if build_all is not None:
+        hook["build_all"] = build_all
     return acquire_correlated_view(
         sessions,
         bom_paths=bom_paths,
@@ -199,6 +356,7 @@ def _correlated(
     root: Path | None,
     session_ids: tuple[str, ...],
     attach_advisories: Any,
+    build_all: Any = None,
 ) -> Acquired:
     """Everything up to the judging, shared by both entry points."""
     return _acquire(
@@ -211,6 +369,7 @@ def _correlated(
         bom_paths=bom_paths,
         project_map=project_map,
         attach_advisories=attach_advisories,
+        build_all=build_all,
     )
 
 
@@ -258,9 +417,18 @@ def analyse_progressively(
     preview: timedelta | None = PREVIEW_WINDOW,
     cache: VerdictCache | None = None,
     attach_advisories: Any = None,
+    analyzer: str = NO_ANALYZER,
+    jev_key: str | None = None,
+    history: DriftHistory | None = None,
+    reasoning: bool = False,
+    budget: int = DEFAULT_BUDGET,
 ) -> Iterator[Analysis]:
     """The same pipeline, delivered in instalments.
 
+    `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`).
+
     `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
     the work splits about 6.6s to collect and correlate, then about 12ms to
@@ -289,11 +457,13 @@ def analyse_progressively(
     `cache` is read and never written. A session graded by an earlier
     `detect --reasoning` shows that grade here; this path never commissions one.
 
-    **No `reasoning` parameter, deliberately.** Stage 3's budget is per *run*, so
-    judging in batches would give each batch its own budget and spend a multiple
-    of what was authorised. A streaming reasoning run needs a budget shared across
-    batches; until it has one, this path does not offer the option rather than
-    offering it wrongly.
+    **Reasoning runs once, after the batches, never inside them.** Stage 3's
+    budget is per *run*, so asking each batch would give each its own budget and
+    spend a multiple of what was authorised — which is why this path refused the
+    option entirely until now. Running it once over the whole view keeps the
+    budget meaning what the flag said, and keeps the ordering that matters: the
+    cheap stages paint first and stage 3 arrives as one more instalment, rather
+    than holding the first paint behind several hundred sequential requests.
     """
     window_end = datetime.now(UTC)
     window_start = since if isinstance(since, datetime) else parse_since(since)
@@ -348,20 +518,43 @@ def analyse_progressively(
     if preview is None:
         yield _stage(DetectorRun(collection_failures=failures), ())
 
+    # Newest *activity* first, not newest start. This decides which sessions are
+    # judged first and therefore what a progressive reader sees first, and
+    # `started_at` answers a different question: a session running for a day
+    # began long ago and is the most recent thing on the machine. Ordering by
+    # its start put the session doing the work behind sessions idle for hours --
+    # the same defect the monitor's own session list had, one layer up, so the
+    # batch order and the page's order now read the same clock.
     ordered = sorted(
         view.sessions,
-        key=lambda correlated: correlated.session.started_at or datetime.min.replace(tzinfo=UTC),
+        key=lambda correlated: (
+            correlated.session.last_activity_at
+            or correlated.session.started_at
+            or datetime.min.replace(tzinfo=UTC)
+        ),
         reverse=True,
     )
     step = max(batch, 1)
-    accumulated = DetectorRun(collection_failures=failures)
+    accumulated = DetectorRun(collection_failures=failures, analyzer=analyzer)
     for index in range(0, len(ordered), step):
         judged = run_detector(
             CorrelatedView(sessions=tuple(ordered[index : index + step])),
             # Read, never written, and never requesting: a session an earlier
             # `detect --reasoning` graded renders with that grade here, and this
-            # path commissions nothing (ADR-0026 clause 2).
+            # path commissions nothing (ADR-0026 clause 2). The analyzer name
+            # is what lets a stored Jev map be served: the cache key carries
+            # the analyzer's identity, so a page started with --analyzer jev
+            # reads the entries that flag paid for and no others.
+            #
+            # `jev_key` rides along although this path asks nothing. Today the
+            # cache key reads `identity()`, which does not depend on the key,
+            # so omitting it would work — but it would leave one call building
+            # two differently-configured analyzers under one name, and the next
+            # thing to depend on the key would break here and not in the
+            # instalment below.
             cache=cache,
+            analyzer=analyzer,
+            jev_key=jev_key,
         )
         accumulated = DetectorRun(
             detections=accumulated.detections + judged.detections,
@@ -370,6 +563,26 @@ def analyse_progressively(
             requested=accumulated.requested + judged.requested,
             analysed=accumulated.analysed + judged.analysed,
             cache_hits=accumulated.cache_hits + judged.cache_hits,
+            maps=accumulated.maps + judged.maps,
             collection_failures=failures,
+            analyzer=analyzer,
         )
         yield _stage(accumulated, tuple(ordered))
+
+    if not reasoning or not ordered:
+        return
+
+    # One more instalment, one run, one budget. Everything above has already
+    # been published, so the page is complete and readable while this is in
+    # flight — on a large window it is several hundred sequential requests and
+    # holding the first paint behind it is what made the page look hung.
+    judged = run_detector(
+        view,
+        reasoning=True,
+        budget=budget,
+        cache=cache,
+        analyzer=analyzer,
+        jev_key=jev_key,
+        history=history,
+    )
+    yield _stage(judged, tuple(ordered))

stacktrace_cli/build.py

@@ -0,0 +1,130 @@
+"""Which commit this install was built from, when it was not a PyPI release.
+
+Read from the install's own PEP 610 record (`direct_url.json` in the
+dist-info), which pip and uv write for every install that did not come from an
+index:
+
+- ``pip install git+https://…@branch`` / ``uv tool install git+…`` record the
+  resolved commit in ``vcs_info.commit_id``.
+- ``pip install -e .`` / ``uv sync`` record an editable ``file://`` URL; the
+  code runs from that checkout, so its current ``HEAD`` is the answer, plus
+  ``.dirty`` when the worktree has uncommitted changes.
+
+A wheel from PyPI has no record, and a non-editable install from a local
+directory records only the path, whose ``HEAD`` may have moved since the build
+— both answer `None` rather than a commit that may not be the one running.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import re
+import subprocess
+import threading
+from importlib.metadata import distribution
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+DISTRIBUTION = "stacktrace-cli"
+
+_SHA = re.compile(r"^[0-9a-f]{7,64}$")
+_SHORT = 7
+
+#: Serializes `_compute_version_label`'s cache misses. `functools.cache` alone
+#: lets concurrent misses run the wrapped function more than once (verified:
+#: two threads racing an uncached call both entered `build_commit`), so the
+#: daemon's startup warm-up (`daemon/runtime.py`) and a request thread could
+#: each launch their own `git` probe. Held only around the call: the thread
+#: that loses the race blocks briefly here rather than repeating the winner's
+#: work, and finds the answer already cached once it gets in.
+_version_label_lock = threading.Lock()
+
+
+def version_label() -> str:
+    """The version as `--version` prints it: `0.4.0`, or `0.4.0+86eef86` for a
+    build from a branch or a pull request.
+
+    One expression for both places that report it, the CLI and telemetry, so a
+    PostHog event and `--version` cannot disagree about which build ran.
+    """
+    with _version_label_lock:
+        return _compute_version_label()
+
+
+@functools.cache
+def _compute_version_label() -> str:
+    from . import __version__
+
+    commit = build_commit()
+    return f"{__version__}+{commit}" if commit else __version__
+
+
+def build_commit() -> str | None:
+    """The short commit this install runs, or `None` for a release install."""
+    try:
+        return _read_build_commit()
+    except Exception:  # noqa: BLE001 - direct_url.json is external, untrusted input
+        # Every step below reads or parses `direct_url.json`, an external
+        # document written by pip or uv. Three narrower guards in a row each
+        # missed a new failure mode in turn (`UnicodeDecodeError` from
+        # `read_text`'s UTF-8 decode, `urlparse`'s `ValueError` on a malformed
+        # URL, `json.loads`'s `RecursionError` on deep nesting) -- the fix is
+        # the boundary, not the exception list. Anything this parse can raise
+        # reads the same as no record.
+        return None
+
+
+def _read_build_commit() -> str | None:
+    raw = distribution(DISTRIBUTION).read_text("direct_url.json")
+    if not raw:
+        return None
+    record = json.loads(raw)
+    if not isinstance(record, dict):
+        return None
+
+    vcs = record.get("vcs_info")
+    if isinstance(vcs, dict):
+        commit = vcs.get("commit_id")
+        if vcs.get("vcs") == "git" and isinstance(commit, str) and _SHA.match(commit):
+            return commit[:_SHORT]
+        return None
+
+    directory = record.get("dir_info")
+    url = record.get("url")
+    if isinstance(directory, dict) and directory.get("editable") is True and isinstance(url, str):
+        parsed = urlparse(url)
+        if parsed.scheme == "file":
+            return _checkout_commit(Path(unquote(parsed.path)))
+    return None
+
+
+def _checkout_commit(root: Path) -> str | None:
+    # GIT_DIR/GIT_WORK_TREE in the caller's environment override -C, so a
+    # caller running us from inside another repo's hook can make git report
+    # that repo's HEAD instead of `root`'s.
+    env = {k: v for k, v in os.environ.items() if k not in ("GIT_DIR", "GIT_WORK_TREE")}
+
+    def git(*args: str) -> str | None:
+        try:
+            done = subprocess.run(
+                ["git", "-C", str(root), *args],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+                env=env,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        return done.stdout if done.returncode == 0 else None
+
+    head = git("rev-parse", "HEAD")
+    if head is None or not _SHA.match(head.strip()):
+        return None
+    commit = head.strip()[:_SHORT]
+    status = git("status", "--porcelain")
+    if status is None:
+        return None
+    return f"{commit}.dirty" if status else commit