stacktrace-cli 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
-"""Placeholder CLI package for Stacktrace.ai."""
+"""The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

stacktrace_cli/analysis.py

@@ -0,0 +1,375 @@
+"""The read pipeline, in the one place that knows its order.
+
+`run_detector` takes a `CorrelatedView`, not a `SessionView`, so
+sessions -> correlate -> detect is stitched by the caller. It was stitched
+twice — once in `cli.py`'s `detect`, once in `sync_detect.py` — and `monitor`
+would have been the third copy of an order that must not differ between them.
+A page showing different findings from the command, for no reason but a
+divergent call site, is the failure this module exists to prevent.
+
+Both halves of the result travel together because neither is recoverable from
+the other: `run` carries the findings, and `view` carries the component a call
+resolved to and the coverage a reader weighs them against.
+
+This module knows nothing about Click. Every caller renders an error its own
+way — a `ClickException` at the command line, a `SyncError` on the upload path —
+so the failures here are `ValueError`, and the message is the one the upload
+path's tests already pin.
+"""
+
+from __future__ import annotations
+
+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 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.run import (
+    DEFAULT_BUDGET,
+    DEFAULT_SAMPLE_BUDGET,
+    DetectorRun,
+    run_detector,
+)
+from stacktrace_cli.sessions.access import SessionView, collect_sessions
+
+
+@dataclass(frozen=True)
+class Analysis:
+    """One run of the read pipeline, and the window it read."""
+
+    run: DetectorRun
+    #: The correlated record the detector judged. Kept because a consumer needs
+    #: what a call resolved to — `monitor` renders it, `sync detect` counts it —
+    #: and a `Detection` carries neither the resolution nor the coverage.
+    view: CorrelatedView
+    #: `parse_since`'s cutoff, retained. Nothing downstream of session
+    #: selection needed it before, so nothing kept it.
+    window_start: datetime
+    #: `now(UTC)` taken *before* collection, so the window never claims to
+    #: cover a session that arrived while the pipeline was running.
+    window_end: datetime
+    #: Whether correlation has run. `False` only on `analyse_progressively`'s
+    #: preview stages, which carry the sessions and their built-in activity
+    #: before a composition has been built — so a consumer knows that coverage
+    #: is not yet countable and that only calls needing no composition are
+    #: listed. `analyse` is always placed.
+    placed: bool = True
+
+
+def parse_since(value: str) -> datetime:
+    """`7d` or `7` -> an aware UTC cut-off.
+
+    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()
+    try:
+        days = int(text[:-1]) if text.endswith("d") else int(text)
+    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}")
+    try:
+        return datetime.now(UTC) - timedelta(days=days)
+    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
+
+
+def _only(view: SessionView, session_ids: tuple[str, ...]) -> SessionView:
+    """The window narrowed to named sessions, 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.
+    """
+    if not session_ids:
+        return view
+    wanted = set(session_ids)
+    return replace(view, sessions=tuple(s for s in view.sessions if s.session_id in wanted))
+
+
+def analyse(
+    *,
+    agent_kinds: tuple[str, ...] = (),
+    since: str | datetime = "7d",
+    bom_paths: tuple[Path, ...] = (),
+    project_map: tuple[str, ...] = (),
+    root: Path | None = None,
+    session_ids: tuple[str, ...] = (),
+    escalate: bool = False,
+    budget: int = DEFAULT_BUDGET,
+    sample_budget: int = DEFAULT_SAMPLE_BUDGET,
+    cache: VerdictCache | None = None,
+    attach_advisories: Any = None,
+) -> Analysis:
+    """Read this machine's sessions, correlate them, and judge them.
+
+    `window_end` is taken before collection rather than after: a window that
+    ends when the pipeline finished would claim to cover a session that started
+    while it ran.
+
+    `attach_advisories` is correlation's own seam. A long-lived process passes a
+    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.
+
+    `session_ids` narrows the window to named sessions. Empty means the whole
+    window, which is what every command passes; monitor's escalate 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.
+    """
+    window_end = datetime.now(UTC)
+    window_start = since if isinstance(since, datetime) else parse_since(since)
+    acquired = _correlated(
+        agent_kinds=agent_kinds,
+        window_start=window_start,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        root=root,
+        session_ids=session_ids,
+        attach_advisories=attach_advisories,
+    )
+    run = run_detector(
+        acquired.view,
+        escalate=escalate,
+        budget=budget,
+        sample_budget=sample_budget,
+        cache=cache,
+    )
+    return Analysis(
+        run=run,
+        view=acquired.view,
+        window_start=window_start,
+        window_end=window_end,
+    )
+
+
+#: How far back the first, cheap read goes. Collection scales with the window
+#: on a fixed floor — measured at 0.24s for a minute, 0.33s for an hour and
+#: 1.20s for three days — so reading the newest hour first is what puts rows on
+#: screen in a third of a second instead of one and a half.
+PREVIEW_WINDOW = timedelta(hours=1)
+
+
+def _collected(
+    *,
+    agent_kinds: tuple[str, ...],
+    window_start: datetime,
+    root: Path | None,
+    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)
+
+
+def _acquire(
+    sessions: SessionView,
+    *,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    attach_advisories: Any,
+) -> Acquired:
+    """Correlate what was read."""
+    hook = {} if attach_advisories is None else {"attach_advisories": attach_advisories}
+    return acquire_correlated_view(
+        sessions,
+        bom_paths=bom_paths,
+        project_map=tuple(parse_mapping(mapping) for mapping in project_map),
+        **hook,
+    )
+
+
+def _correlated(
+    *,
+    agent_kinds: tuple[str, ...],
+    window_start: datetime,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    root: Path | None,
+    session_ids: tuple[str, ...],
+    attach_advisories: Any,
+) -> Acquired:
+    """Everything up to the judging, shared by both entry points."""
+    return _acquire(
+        _collected(
+            agent_kinds=agent_kinds,
+            window_start=window_start,
+            root=root,
+            session_ids=session_ids,
+        ),
+        bom_paths=bom_paths,
+        project_map=project_map,
+        attach_advisories=attach_advisories,
+    )
+
+
+def _unplaced(sessions: SessionView, *, window_start: datetime, window_end: datetime) -> Analysis:
+    """The sessions as read, before anything has been correlated or judged.
+
+    Correlation is 2.7s of a 4.4s first paint and it places 0.9% of calls; the
+    other 99% are built-in tools, which need no composition at all. So this
+    carries every session read and lets the render list the calls a
+    composition is not needed for — coverage stays uncounted, and no finding is
+    claimed, because neither is known yet.
+    """
+    return Analysis(
+        run=DetectorRun(
+            collection_failures=run_detector(
+                CorrelatedView(unavailable=sessions.unavailable)
+            ).collection_failures
+        ),
+        view=CorrelatedView(
+            unavailable=sessions.unavailable,
+            sessions=tuple(
+                CorrelatedSession(
+                    session=session,
+                    composition=None,
+                    resolutions={},
+                    coverage=Coverage(total=0, resolved=0, by_outcome={}, by_component_type={}),
+                )
+                for session in sessions.sessions
+            ),
+        ),
+        window_start=window_start,
+        window_end=window_end,
+        placed=False,
+    )
+
+
+def analyse_progressively(
+    *,
+    agent_kinds: tuple[str, ...] = (),
+    since: str | datetime = "7d",
+    bom_paths: tuple[Path, ...] = (),
+    project_map: tuple[str, ...] = (),
+    root: Path | None = None,
+    batch: int = 8,
+    preview: timedelta | None = PREVIEW_WINDOW,
+    cache: VerdictCache | None = None,
+    attach_advisories: Any = None,
+) -> Iterator[Analysis]:
+    """The same pipeline, delivered in instalments.
+
+    `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
+    judge each session — so a caller that waits for the whole run shows nothing
+    for six seconds while already holding the sessions and their activity.
+
+    Three kinds of yield, cheapest first.
+
+    **Preview stages, before correlation** (`placed=False`). Correlation is
+    2.7s of a 4.4s first paint and it places 0.9% of a real window's calls; the
+    other 99% are built-in tools, which `join.py`'s predicates answer for in a
+    millisecond. So the sessions and those calls go out first — the newest
+    `preview` of them, then the whole window — and the page fills in ~0.35s
+    rather than ~4.4s. Pass `preview=None` for attributed data only.
+
+    **Then batches of judged sessions**, newest first, because someone watching
+    a machine cares about what just happened and should not have to scroll for
+    it. Every one of these carries the *whole* session list: the preview
+    already published it, and a later stage carrying fewer would make the count
+    on the page go backwards.
+
+    The last yield equals what `analyse` would have returned. If it did not,
+    the page and the command would disagree, which is the thing one pipeline
+    exists to prevent.
+
+    `cache` is read and never written. A session graded by an earlier
+    `detect --escalate` shows that grade here; this path never commissions one.
+
+    **No `escalate` 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 escalation needs a budget shared across
+    batches; until it has one, this path does not offer the option rather than
+    offering it wrongly.
+    """
+    window_end = datetime.now(UTC)
+    window_start = since if isinstance(since, datetime) else parse_since(since)
+
+    def read(cutoff: datetime) -> SessionView:
+        return _collected(agent_kinds=agent_kinds, window_start=cutoff, root=root, session_ids=())
+
+    if preview is not None:
+        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)
+
+    sessions = read(window_start)
+    if preview is not None:
+        yield _unplaced(sessions, window_start=window_start, window_end=window_end)
+
+    view = _acquire(
+        sessions,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        attach_advisories=attach_advisories,
+    ).view
+
+    def _stage(run: DetectorRun, sessions: tuple[CorrelatedSession, ...]) -> Analysis:
+        """One instalment: every session, and the findings judged so far.
+
+        The whole session list, every time. It grew with the findings until the
+        preview stages existed — the point then was that the feed should not
+        appear all at once — but the preview publishes every session within
+        ~1.6s and a client that paces its own reveal streams them in anyway. A
+        stage carrying fewer sessions than the preview did would make the count
+        on the page go backwards.
+        """
+        return Analysis(
+            run=run,
+            view=replace(view, sessions=sessions),
+            window_start=window_start,
+            window_end=window_end,
+        )
+
+    # The detector derives these from the view, and a stage that has not judged
+    # anything yet still has to carry them: a reader that failed is the one
+    # thing a page must never render as silence.
+    failures = run_detector(CorrelatedView(unavailable=view.unavailable)).collection_failures
+
+    # Stage zero: what could not be read, before a session is judged. A reader
+    # that failed is the one thing a page must never render as silence, and it
+    # is known before the detector has done anything at all. Skipped when a
+    # preview already carried it, since that stage said the same and carried
+    # the sessions too.
+    if preview is None:
+        yield _stage(DetectorRun(collection_failures=failures), ())
+
+    ordered = sorted(
+        view.sessions,
+        key=lambda correlated: correlated.session.started_at or datetime.min.replace(tzinfo=UTC),
+        reverse=True,
+    )
+    step = max(batch, 1)
+    accumulated = DetectorRun(collection_failures=failures)
+    for index in range(0, len(ordered), step):
+        judged = run_detector(
+            CorrelatedView(sessions=tuple(ordered[index : index + step])),
+            # Read, never written, and never escalating: a session an earlier
+            # `detect --escalate` graded renders with that grade here, and this
+            # path commissions nothing (ADR-0026 clause 2).
+            cache=cache,
+        )
+        accumulated = DetectorRun(
+            detections=accumulated.detections + judged.detections,
+            unknowns=accumulated.unknowns + judged.unknowns,
+            sessions=accumulated.sessions + judged.sessions,
+            escalated=accumulated.escalated + judged.escalated,
+            analysed=accumulated.analysed + judged.analysed,
+            cache_hits=accumulated.cache_hits + judged.cache_hits,
+            collection_failures=failures,
+        )
+        yield _stage(accumulated, tuple(ordered))

stacktrace_cli/cli.py

@@ -25,12 +25,12 @@ import click
 from openaca.cli import main as openaca_cli
 
 from . import __version__
-from .correlate.orchestrate import acquire_correlated_view
-from .correlate.project_map import parse_mapping
+from .analysis import analyse, parse_since
 from .detector.cache import VerdictCache, default_directory
 from .detector.render import render_json as render_detections_json
 from .detector.render import render_text as render_detections_text
-from .detector.run import DEFAULT_BUDGET, DEFAULT_SAMPLE_BUDGET, run_detector
+from .detector.run import DEFAULT_BUDGET, DEFAULT_SAMPLE_BUDGET
+from .monitor.server import serve
 from .remote.cli import main as remote_cmd
 from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
@@ -50,6 +50,36 @@ def _parse_since(value: str) -> datetime:
     return datetime.now(UTC) - timedelta(days=int(match.group(1)))
 
 
+def _window_start(ctx: click.Context, param: click.Parameter, value: str) -> datetime:
+    """`detect`'s window, resolved by this command's own parser.
+
+    The window otherwise reaches `analyse` as a string and is parsed there, by
+    the parser that also answers the upload path — whose value comes from a
+    config file rather than a shell, so it is more forgiving about the spelling
+    and stricter about the count. Applying it here as well would quietly change
+    what this command accepts, so the cutoff travels already resolved.
+    """
+    return _parse_since(value)
+
+
+def _day_count(ctx: click.Context, param: click.Parameter, value: str) -> str:
+    """Refuse here every `--since` the pipeline would refuse later.
+
+    The window reaches `analyse` as a string and is parsed there, once for every
+    caller. That parser also answers the upload path, whose value comes from a
+    config file rather than a shell, so it is the more forgiving of the two —
+    and the narrower spelling stays here, where a mistyped option is a usage
+    error with the usage line attached rather than a command that started,
+    read nothing and failed.
+    """
+    _parse_since(value)
+    try:
+        parse_since(value)
+    except ValueError as error:
+        raise click.BadParameter(str(error)) from error
+    return value
+
+
 def _show_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
     # Click invokes an eager option's callback on every invocation of the
     # group, with `value=False` when the flag was absent, so an unguarded
@@ -165,7 +195,13 @@ def sessions(
 
 @click.command()
 @click.option("--agent-kind", "agent_kinds", multiple=True, help="Limit to these agent kinds.")
-@click.option("--since", default="7d", show_default=True, help="How far back to read.")
+@click.option(
+    "--since",
+    default="7d",
+    show_default=True,
+    callback=_window_start,
+    help="How far back to read.",
+)
 @click.option(
     "--bom",
     "bom_paths",
@@ -239,7 +275,7 @@ def sessions(
 )
 def detect(
     agent_kinds: tuple[str, ...],
-    since: str,
+    since: datetime,
     bom_paths: tuple[Path, ...],
     output_format: str,
     detail: bool,
@@ -275,23 +311,26 @@ def detect(
     components a session invoked to osv.dev. Coordinates only -- never a
     prompt, an argument or a result.
     """
-    view = collect_sessions(list(agent_kinds) or None, _parse_since(since), root=root)
     try:
-        acquired = acquire_correlated_view(
-            view, bom_paths=bom_paths, project_map=tuple(parse_mapping(m) for m in project_map)
+        # One call, because the order it runs in is `analysis.py`'s to know:
+        # `monitor` and `sync detect` read the same pipeline and must not be
+        # able to disagree with this command about what it found.
+        analysis = analyse(
+            agent_kinds=agent_kinds,
+            since=since,
+            bom_paths=bom_paths,
+            project_map=project_map,
+            root=root,
+            escalate=escalate,
+            budget=budget,
+            sample_budget=sample_budget,
+            # Only ever consulted when stage 3 runs: there is nothing to reuse
+            # otherwise, and opening a directory to discover that is waste.
+            cache=VerdictCache(default_directory()) if cache and escalate else None,
         )
     except ValueError as error:
         raise click.ClickException(str(error)) from error
-
-    result = run_detector(
-        acquired.view,
-        escalate=escalate,
-        budget=budget,
-        sample_budget=sample_budget,
-        # Only ever consulted when stage 3 runs: there is nothing to reuse
-        # otherwise, and opening a directory to discover that is waste.
-        cache=VerdictCache(default_directory()) if cache and escalate else None,
-    )
+    result = analysis.run
     output = (
         render_detections_json(result)
         if output_format == "json"
@@ -300,6 +339,122 @@ def detect(
     click.echo(output, nl=not output.endswith("\n"))
 
 
+@click.command()
+@click.option("--port", type=int, default=0, help="Serve on this port instead of an unused one.")
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    show_default=True,
+    help="Loopback only. This page renders working directories and matched "
+    "values, so a non-loopback address is refused rather than warned about.",
+)
+@click.option(
+    "--interval",
+    # Above zero, not merely non-negative: the wait between passes is what
+    # makes this page free to leave open, and `Event.wait(0)` returns at once —
+    # a zero or negative interval walks the transcript tree in a hot loop.
+    type=click.FloatRange(min=0, min_open=True),
+    default=4.0,
+    show_default=True,
+    help="Seconds between checks for new agent activity. A pass is skipped "
+    "entirely when nothing on disk has changed.",
+)
+@click.option(
+    "--escalate/--no-escalate",
+    default=False,
+    show_default=True,
+    help="Let the page send one session to the agent's own CLI for semantic "
+    "analysis. Off by default: stage 3 spends your provider quota, and a page "
+    "left open is the wrong place for that to be implicit. Capped by --budget.",
+)
+@click.option(
+    "--budget",
+    type=click.IntRange(min=1),
+    default=DEFAULT_BUDGET,
+    show_default=True,
+    help="Escalations this monitor may spend in total, if --escalate is on.",
+)
+@click.option(
+    "--no-open", is_flag=True, default=False, help="Print the URL, do not open a browser."
+)
+@click.option("--agent-kind", "agent_kinds", multiple=True, help="Limit to these agent kinds.")
+@click.option(
+    "--since",
+    default="3d",
+    show_default=True,
+    callback=_day_count,
+    help="How far back to read. Shorter than `detect`'s week deliberately: the "
+    "whole window is collected and correlated before the page can render "
+    "anything — measured at ~2.5s for a day and ~6s for a week of a busy "
+    "machine — and a live view is about what is happening rather than what "
+    "happened. Widen it when you want the history.",
+)
+@click.option(
+    "--bom",
+    "bom_paths",
+    multiple=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Use this Agent BOM instead of scanning for its kind.",
+)
+@click.option(
+    "--project-map",
+    "project_map",
+    multiple=True,
+    metavar="OLD=NEW",
+    help="Where a project a session ran in lives now, for a directory that has moved.",
+)
+@click.option(
+    "--root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Read agent transcripts from here instead of the default location.",
+)
+def monitor(
+    port: int,
+    host: str,
+    interval: float,
+    escalate: bool,
+    budget: int,
+    no_open: bool,
+    agent_kinds: tuple[str, ...],
+    since: str,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    root: Path | None,
+) -> None:
+    """Watch this machine's agents in a browser, live.
+
+    Serves a local page — a summary, what your agents are doing, and what the
+    detector makes of it — refreshing as they work. Everything on it is
+    computed in this process by the same code `stacktrace detect` runs; the
+    page renders and never judges.
+
+    Loopback only, and free to leave open: a pass is skipped when nothing has
+    changed, advisory lookups are asked once per component, and the two stages
+    that need no model are the only ones that run. --escalate adds a button
+    that spends your provider quota, off unless asked for.
+    """
+    try:
+        code = serve(
+            host=host,
+            port=port,
+            interval=interval,
+            escalate=escalate,
+            budget=budget,
+            open_browser=not no_open,
+            echo=click.echo,
+            agent_kinds=agent_kinds,
+            since=since,
+            bom_paths=bom_paths,
+            project_map=project_map,
+            root=root,
+        )
+    except (OSError, ValueError) as error:
+        raise click.ClickException(str(error)) from error
+    if code:
+        raise click.exceptions.Exit(code)
+
+
 # Named, never discovered: an upstream release must not be able to enlarge this
 # CLI. A missing name is a `KeyError` at import time, which names the command
 # and the line, and lands at upgrade time.
@@ -312,3 +467,4 @@ for _name in PASSTHROUGH:
 main.add_command(remote_cmd, "remote")
 main.add_command(sessions)
 main.add_command(detect)
+main.add_command(monitor)

stacktrace_cli/correlate/acquire.py

@@ -31,6 +31,7 @@ from stacktrace_cli.correlate.composition import (
     Composition,
     composition_from_bom,
     reject_malformed_shape,
+    root_property,
 )
 
 _AGENT_KIND_PROPERTY = "openaca:agent_kind"
@@ -362,12 +363,7 @@ def _text_or_absent(value: object) -> bool:
 
 
 def _declared_kind(document: dict[str, Any]) -> str | None:
-    metadata = document.get("metadata")
-    root = metadata.get("component") if isinstance(metadata, dict) else None
-    if not isinstance(root, dict):
-        return None
-    for prop in root.get("properties") or []:
-        if isinstance(prop, dict) and prop.get("name") == _AGENT_KIND_PROPERTY:
-            value = prop.get("value")
-            return value if isinstance(value, str) else None
-    return None
+    """The kind property, read by the same walk that reads every other root
+    property. Kept as a name of its own because the *discriminator* is what
+    this module reads before it has anything to ask — see `load_bom`."""
+    return root_property(document, _AGENT_KIND_PROPERTY)