stacktrace-cli 0.7.1__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.7.1"
+__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

@@ -38,12 +38,19 @@ from .options import analyzer_option, resolve_analyzer
 from .remote.cli import main as remote_cmd
 from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
-from .telemetry import emit_error
+from .telemetry import command_of, emit, emit_error
 from .telemetry.cli import telemetry as telemetry_cmd
+from .telemetry.events import remember_internal
 from .webhook.cli import webhook as webhook_cmd
 
 PASSTHROUGH: Final = ("scan", "bom", "policy")
 
+#: Commands whose runs are never counted as `command_run` (ADR-0090).
+#: `telemetry` is where the answer is given and read back: reading the
+#: preference or turning it off must not send an event or create an identity,
+#: and `telemetry on` already says what it did with `installed`.
+UNCOUNTED: Final = frozenset({"telemetry"})
+
 HOMEPAGE = "https://stacktrace.ai"
 
 #: The unit is required here and optional in `analysis.parse_since`. That is
@@ -129,13 +136,24 @@ class SectionedGroup(click.Group):
     """
 
     def invoke(self, ctx: click.Context) -> object:
-        """Run the command; count an exception on the way out, and only an exception.
-
-        Click's own control flow travels as exceptions too -- `Exit` from a
-        pass-through's exit code, `Abort` on Ctrl-C, `UsageError` on a typo --
-        and a bare one is not an error in this program. Everything else is,
-        and only an allowlisted class name or `other` leaves (ADR-0039). A
-        command that succeeds performs no telemetry work at all.
+        """Run the command; count a completed run, or an exception, on the way out.
+
+        A command that completes -- returns, or ends with `sys.exit(0)` the way
+        an OpenACA pass-through does -- hands off exactly one `command_run`
+        naming it from `telemetry.events.COMMANDS`, and nothing else
+        (ADR-0090). That hand-off is `emit`: no network I/O on this path, and
+        a failure of any kind is swallowed there. `UNCOUNTED` commands hand
+        off nothing.
+
+        Click's own control flow travels as exceptions too -- `Exit` from help
+        or a pass-through's exit code, `Abort` on Ctrl-C, `UsageError` on a
+        typo -- and a bare one is neither a completed run nor an error in this
+        program, so it sends nothing and creates no identity. That includes
+        `Exit(0)`: it is how `--help` ends, so a command that means "done"
+        returns rather than calling `ctx.exit()`. `--version` and the group's
+        own help end before this method runs. Everything else is an error,
+        and only an allowlisted class name or `other` leaves (ADR-0039); a
+        failed command is counted as its `error`, not as a run.
 
         A `ClickException` or an `Exit` a command site raised to wrap a real
         failure (`raise click.ClickException(...) from exc`, or
@@ -158,21 +176,35 @@ class SectionedGroup(click.Group):
         invalid arguments from the `error` metric. This package's own
         operational wrappers always raise a bare `click.ClickException`, never
         `UsageError`, to carry a real cause.
+
+        `UNCOUNTED` is checked on every path that would otherwise call
+        `emit_error`, not only `_count_run`'s: `telemetry off` wraps a failed
+        preference write in a caused `ClickException` the same way any other
+        operational wrapper does, and ADR-0090 requires that using `telemetry`
+        itself never creates an identity or sends an event, whether it
+        completes or fails (Codex review, PR #153).
         """
         try:
-            return super().invoke(ctx)
+            result = super().invoke(ctx)
+        except SystemExit as exit_:
+            if exit_.code in (None, 0):
+                _count_run(ctx)
+            raise
         except click.exceptions.Abort:
             raise
         except click.UsageError:
             raise
         except (click.exceptions.Exit, click.ClickException) as error:
             cause = error.__cause__
-            if cause is not None:
-                emit_error(cause)
+            if cause is not None and ctx.invoked_subcommand not in UNCOUNTED:
+                emit_error(cause, "cli")
             raise
         except Exception as error:
-            emit_error(error)
+            if ctx.invoked_subcommand not in UNCOUNTED:
+                emit_error(error, "cli")
             raise
+        _count_run(ctx)
+        return result
 
     def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         commands: list[tuple[str, click.Command]] = []
@@ -201,6 +233,12 @@ class SectionedGroup(click.Group):
                 formatter.write_dl(rows)
 
 
+def _count_run(ctx: click.Context) -> None:
+    name = ctx.invoked_subcommand
+    if name not in UNCOUNTED:
+        emit("command_run", command=command_of(name))
+
+
 @click.group(cls=SectionedGroup)
 @click.option(
     "--version",
@@ -212,6 +250,9 @@ class SectionedGroup(click.Group):
 )
 def main() -> None:
     """Stacktrace: agent composition analysis, detection and upload."""
+    # Before any command, so `STACKTRACE_INTERNAL` set in a shell reaches the
+    # daemon that command may start, which never reads a shell (ADR-0091).
+    remember_internal()
 
 
 @click.command()
@@ -365,11 +406,14 @@ def detect(
 ) -> None:
     """Find security and reliability findings in what agents did.
 
-    Three kinds of finding, under two families: a credential reaching an
-    outbound call and success reported against evidence of failure are
-    security; why the agent stopped, and who can unblock it, is reliability.
+    Four kinds of finding, under two families: a credential reaching an
+    outbound call, success reported against evidence of failure, and an
+    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
@@ -378,7 +422,9 @@ def detect(
     "On a default run" is the whole of the qualification, and it is here rather
     than left to the flags: `--reasoning --analyzer jev` adds a third stage
     that sends per-call windows -- a completion claim, one verification command
-    and its output -- to TypeSafe's Jev (ADR-0033). Both flags must be typed,
+    and its output; and, for a mutating infrastructure command, that command
+    with the user's own requests in the session -- to TypeSafe's Jev
+    (ADR-0033). Both flags must be typed,
     neither has a default, and this output names them when a session is left
     unjudged, so it is a run a reader can ask for and therefore one this
     paragraph has to account for.

stacktrace_cli/correlate/observed.py

@@ -1334,18 +1334,6 @@ def observed_across(*calls: ToolCallLike | None) -> tuple[str, ...]:
     return tuple(sorted(names))
 
 
-def evidence_for(call: ToolCallLike, capability: str) -> dict[str, str] | None:
-    """What established this capability on this call, for a rule that cites it.
-
-    A grade alone tells a reader how sure to be; this tells them why, which is
-    what makes the grade checkable rather than an assertion.
-    """
-    for observation in observe(call):
-        if observation.capability == capability:
-            return dict(observation.evidence)
-    return None
-
-
 def command_heads(command: object) -> tuple[str, ...]:
     """Every program a shell command runs, without its arguments.
 
@@ -1361,8 +1349,10 @@ def command_heads(command: object) -> tuple[str, ...]:
 #: The control operators a command line is split on, longest first so `&&` is
 #: never read as one `&`. `&` alone is deliberately absent, as it was from the
 #: expression this replaces: backgrounding is under-split rather than
-#: mis-split, which costs a segment and never invents one.
-_SEPARATORS = ("&&", "||", ";", "|", "\n")
+#: mis-split, which costs a segment and never invents one. `|&` is a pipe that
+#: carries stderr too, and is reported as `|`: read as `|` and then `&`, its
+#: receiver began with `&` and was dropped as punctuation.
+_SEPARATORS = ("&&", "||", "|&", ";", "|", "\n")
 
 #: Characters after which the shell is at the start of a word, so a `#` there
 #: opens a comment. Blanks and the newline are the ordinary case; the operator
@@ -1386,7 +1376,8 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
 
     Returns ``(segment_text, preceding_operator)`` pairs.  The first segment's
     operator is ``None``; every later segment carries the ``&&``, ``||``, ``;``,
-    ``|`` or ``\\n`` that separated it from the one before it.
+    ``|`` or ``\\n`` that separated it from the one before it (``|&`` is a
+    pipe, and carried as ``|``).
 
     A control operator is an operator **only unquoted and unescaped** — that is
     the shell's own grammar, and it is verified against `bash` itself in
@@ -1474,6 +1465,15 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
             newline = command.find("\n", index)
             index = len(command) if newline == -1 else newline
             continue
+        if command.startswith(">|", index):
+            # The clobbering redirection is one operator: its `|` is not a pipe.
+            # Read as one, `echo safe >| sqlite3 db 'DROP …'` -- which writes a
+            # file named `sqlite3` -- fabricated a piped `sqlite3` (P2, PR #130
+            # review).
+            current.append(">|")
+            index += 2
+            at_word_start = True
+            continue
         separator = next((s for s in _SEPARATORS if command.startswith(s, index)), None)
         if separator is None:
             current.append(char)
@@ -1481,15 +1481,16 @@ def _split_on_separators(command: str) -> list[tuple[str, str | None]]:
             at_word_start = char in _WORD_START_BEFORE_COMMENT
             continue
         segment_text = "".join(current)
+        operator = "|" if separator == "|&" else separator
         if segment_text.strip():
             parts.append((segment_text, preceding_op))
-            preceding_op = separator
+            preceding_op = operator
         else:
             # Two separators with nothing between them (e.g. "&&\n"):
             # keep the conditional operator over a plain terminator so
             # the next real segment inherits the right dependency.
             if separator in ("&&", "||") or preceding_op is None:
-                preceding_op = separator
+                preceding_op = operator
         current = []
         index += len(separator)
         at_word_start = True
@@ -1871,22 +1872,47 @@ def _strip_heredocs(command: str) -> str:
     """Drop heredoc bodies, keeping the lines that introduce them.
 
     A heredoc the shell never sees closed consumes the rest of the input, and
-    so does this: the loop below runs off the end and everything after the
+    so does this: `_heredoc_lines` runs off the end and everything after the
     introducer is dropped. That is bash's own behaviour, not a fallback -- it
     reads to end-of-input looking for a terminator that is not there.
     """
-    kept: list[str] = []
+    return "\n".join(line for line, _bodies in _heredoc_lines(command))
+
+
+def heredoc_bodies(command: str) -> tuple[tuple[str, tuple[str, ...]], ...]:
+    """Each line of `command` that opens heredocs, with their bodies in the
+    order bash reads them.
+
+    What `_strip_heredocs` drops, kept: a body is the text the shell feeds a
+    program's stdin, which is what a caller asking what a program was *given*
+    -- SQL fed to a database client -- needs and `command_segments` never
+    returns. Arithmetic is masked first, as `_readable_commands` masks it, so a
+    `<<` inside `$(( … ))` opens nothing here either.
+    """
+    return tuple(
+        (line, tuple(bodies))
+        for line, bodies in _heredoc_lines(_mask_arithmetic(command))
+        if bodies
+    )
+
+
+def _heredoc_lines(command: str) -> list[tuple[str, list[str]]]:
+    """Each line that is not a heredoc body, with the bodies it opens."""
+    kept: list[tuple[str, list[str]]] = []
     lines = command.splitlines()
     index = 0
     while index < len(lines):
         line = lines[index]
-        kept.append(line)
+        bodies: list[str] = []
+        kept.append((line, bodies))
         index += 1
         # In order, because that is the order bash reads the bodies in: a line
         # opening two heredocs has the first body directly after it and the
         # second after that one's terminator.
         for dash, terminator in _heredoc_introducers(line):
+            start = index
             while index < len(lines) and not _closes_heredoc(lines[index], terminator, dash):
                 index += 1
+            bodies.append("\n".join(lines[start:index]))
             index += 1
-    return "\n".join(kept)
+    return kept

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.
+"""