stacktrace-cli 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

stacktrace/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.11.0"
+__version__ = "0.12.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.py

@@ -52,8 +52,6 @@ PASSTHROUGH: Final = ("scan", "bom", "policy")
 #: 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
 #: the whole of the difference between the two spellings, and it is deliberate:
 #: the forgiving parser also answers the upload path, whose value comes from a

stacktrace/correlate/observed.py

@@ -204,6 +204,12 @@ _NOT_A_BINARY = frozenset(
 #: transport is *unknown*, never local.
 _REMOTE_TRANSPORTS = frozenset({"claudeai-proxy", "http", "https", "sse", "streamable-http"})
 
+
+def declares_remote_transport(transport: str | None) -> bool:
+    """Whether a transport, observed or declared, leaves the machine."""
+    return transport in _REMOTE_TRANSPORTS
+
+
 #: Redirect destinations that are not files. `/dev/null` is the overwhelming
 #: one -- 3,493 of the corpus's 13,514 `>` characters -- and a command sending
 #: output there wrote nothing at all. The rest name an already-open stream, so
@@ -1692,15 +1698,53 @@ def redirect_targets(command: object) -> tuple[str, ...]:
     return tuple(found)
 
 
+#: The shell options that consume the next word, and the ones that answer
+#: themselves and run nothing. The same grammar as `_SHELL_SPEC` in
+#: `detector/deterministic.py`, which a test holds this reader to.
+_SHELL_VALUE_OPTIONS = frozenset({"-O", "+O", "-o", "+o", "--rcfile", "--init-file"})
+_SHELL_TERMINAL_OPTIONS = frozenset({"--help", "--version"})
+
+
 def _shell_command_body(arguments: Sequence[str]) -> str | None:
-    """The command a shell was handed with `-c`, if it was handed one.
+    """The command a shell was handed with `-c`, if it ran it.
 
     `shlex` has already removed the quoting, so the body arrives as one token.
+
+    `-c` may share a word with other short flags: `bash -lc "curl ..."` is a
+    login shell running curl, and reading only a literal `-c` hid it. A value
+    option in the same cluster (`-Oc extglob body`) takes its word first.
+
+    Only the options are walked. The first operand, or `--`, ends them, and
+    what follows is a script's arguments rather than a body. A noexec shell
+    (`-n`, `-o noexec`) and one answering `--help` or `--version` run nothing,
+    so neither has a body.
     """
-    for index, token in enumerate(arguments):
-        if token == "-c" and index + 1 < len(arguments):
-            body = arguments[index + 1]
-            return body if body else None
+    noexec = False
+    index = 0
+    while index < len(arguments):
+        token = arguments[index]
+        if token in ("-n", "+n"):
+            noexec = token == "-n"
+            index += 1
+        elif token in _SHELL_TERMINAL_OPTIONS or token == "--":
+            return None
+        elif token in _SHELL_VALUE_OPTIONS:
+            if token in ("-o", "+o") and "noexec" in arguments[index + 1 : index + 2]:
+                noexec = token == "-o"
+            index += 2
+        elif token.startswith("-") and not token.startswith("--") and len(token) > 1:
+            letters = token[1:]
+            noexec = noexec or "n" in letters
+            if "c" in letters:
+                at = index + 1 + sum(letter in "Oo" for letter in letters)
+                if noexec or at >= len(arguments):
+                    return None
+                return arguments[at] or None
+            index += 1
+        elif token.startswith(("-", "+")):
+            index += 1
+        else:
+            return None
     return None
 
 

stacktrace/cost/baseline.py

@@ -14,7 +14,8 @@ Two halves (ADR-0093):
   never depends on when it was read.
 
 Tokens, never dollars, and recorded tokens only: nothing else ever
-enters a baseline.
+enters a baseline. A response that is not final counts at least the output
+it shows (`cost.output`, ADR-0129).
 """
 
 from __future__ import annotations
@@ -525,6 +526,20 @@ def tokens_by_working_day(summaries: Iterable[Summary], *, before: date) -> dict
     return days
 
 
+def tokens_by_active_slot(
+    summaries: Iterable[Summary], *, before: date
+) -> dict[tuple[date, int], int]:
+    """Recorded tokens in each quarter hour with use, of the 30 days before
+    `before`, on every model: the slots of the working days
+    `tokens_by_working_day` reads."""
+    slots: dict[tuple[date, int], int] = {}
+    for summary in summaries:
+        for on, _model, slot, tokens in dated_slots(summary):
+            if _in_window(on, before):
+                slots[(on, slot)] = slots.get((on, slot), 0) + tokens
+    return slots
+
+
 def _quantile(values: Sequence[float], share: float) -> float:
     if not values:
         return 0.0

stacktrace/cost/copies.py

@@ -0,0 +1,90 @@
+"""Each response once, whichever sessions carry it.
+
+Claude Code's `/branch` and `--fork-session` write a new session holding the
+conversation so far: each record whole, its message id, usage and time
+included, under the new session id. OpenAIDR reads each file as its own
+session and keys a response by its session (its ADR-0014), so without this a
+conversation's tokens would count again in every branch of it.
+
+A response two sessions carry counts in the session that began first, since a
+branch's copies are never older than the conversation they copy: a branch
+holds a subset of its original's records, plus its own later ones. Equal starts
+go by session id, so every reader picks the same session. The usage upload
+files responses by the same rank (`ResponseUse.rank`), and remembers where it
+filed each (`FindingStore.put_usage`), since what it sent cannot move.
+
+A session that lost a response loses that response's turn too: a consumer
+reading tool calls off `turns` (component usage, cost's reason analyzers)
+would otherwise still see the copied conversation's calls, counted again
+under the branch.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Any, TypeVar, cast
+
+from stacktrace.cost.runs import UsageSession
+from stacktrace.sessions.protocols import ModelResponseLike
+
+S = TypeVar("S", bound=UsageSession)
+
+_EARLIEST = datetime.min.replace(tzinfo=UTC)
+
+
+def rank(started_at: datetime | None, session_id: str) -> tuple[bool, datetime, str]:
+    """Which of the sessions carrying one response counts it: the one that
+    began first, one with no start last, then by session id."""
+    return started_at is None, started_at or _EARLIEST, session_id
+
+
+def distinct(sessions: Iterable[S]) -> tuple[S, ...]:
+    """The sessions in their order, each response in only the session ranked
+    first of those carrying it. A session that lost none is returned as it is."""
+    held = list(sessions)
+    # Per kind, then by id: no key object per response, on a month's backfill.
+    owner: dict[str | None, dict[str, str]] = {}
+    for session in sorted(held, key=lambda s: rank(_started(s), s.session_id)):
+        owners = owner.setdefault(session.agent_kind, {})
+        for response in session.responses:
+            owners.setdefault(response.response_id, session.session_id)
+    found: list[S] = []
+    for session in held:
+        owners = owner[session.agent_kind]
+        if all(owners[r.response_id] == session.session_id for r in session.responses):
+            found.append(session)
+            continue
+        own = tuple(r for r in session.responses if owners[r.response_id] == session.session_id)
+        found.append(_without(session, own))
+    return tuple(found)
+
+
+def _started(session: UsageSession) -> datetime | None:
+    return getattr(session, "started_at", None)
+
+
+def _without(session: S, responses: tuple[ModelResponseLike, ...]) -> S:
+    return cast(S, _Without(session, responses))
+
+
+class _Without:
+    """A session less the responses another session counts, and the turns
+    that record them: everything else is the session's own.
+
+    A turn with no response id (a user turn, never carrying tool calls) is
+    always kept: it names no response to own or lose."""
+
+    def __init__(self, session: UsageSession, responses: tuple[ModelResponseLike, ...]) -> None:
+        self._session = session
+        self.responses = responses
+        kept = {r.response_id for r in responses}
+        self.turns = tuple(
+            turn
+            for turn in getattr(session, "turns", ()) or ()
+            if getattr(turn, "response_id", None) is None
+            or getattr(turn, "response_id", None) in kept
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._session, name)

stacktrace/cost/ledger.py

@@ -16,6 +16,8 @@ from collections.abc import Iterable
 from datetime import datetime, timedelta
 from typing import Generic, TypeVar
 
+from stacktrace.cost.copies import distinct
+from stacktrace.cost.output import floored
 from stacktrace.cost.runs import UsageSession
 from stacktrace.sessions.lineage import parent_session_id
 
@@ -31,7 +33,9 @@ class Ledger(Generic[S]):
         self._sessions: dict[tuple[str | None, str], S] = {}
 
     def update(self, sessions: Iterable[S]) -> None:
-        for session in sessions:
+        # Each response not final counts what it shows (`cost.output`), worked
+        # out once per change rather than on every read.
+        for session in floored(sessions):
             self._sessions[(session.agent_kind, session.session_id)] = session
 
     def sessions(self, *, now: datetime) -> tuple[S, ...]:
@@ -51,7 +55,9 @@ class Ledger(Generic[S]):
             for key, session in self._sessions.items()
             if (at := latest[_run_of(session)]) is None or at >= cutoff
         }
-        return tuple(self._sessions.values())
+        # A branch's copies of its conversation count in the conversation
+        # (`cost.copies`): a budget or a run counts each response once.
+        return distinct(self._sessions.values())
 
 
 def _run_of(session: UsageSession) -> tuple[str | None, str]:

stacktrace/cost/measures.py

@@ -222,8 +222,9 @@ def _afresh(
 
 def window_share(response: ModelResponseLike) -> float | None:
     """The share of the model's context window this response was sent, or None
-    for a model whose window is not known."""
-    window = context_window(response.model)
+    for a model whose window is not known. The window the client recorded
+    comes first: it is the one the model ran against."""
+    window = response.context_window or context_window(response.model)
     return None if window is None else context_tokens(response) / window
 
 

stacktrace/cost/models.py

@@ -11,9 +11,10 @@ import re
 
 _MILLION = 1_000_000
 
-#: Claude Code records some models with their snapshot date, such as
-#: `claude-haiku-4-5-20251001`; the model is the name without it.
-_SNAPSHOT = re.compile(r"-\d{8}$")
+#: Clients record some models with their snapshot date, such as
+#: `claude-haiku-4-5-20251001` or OpenAI's `gpt-5.1-2025-11-13`; the model is
+#: the name without it.
+_SNAPSHOT = re.compile(r"-(?:\d{8}|\d{4}-\d{2}-\d{2})$")
 
 CONTEXT_WINDOWS: dict[str, int] = {
     "claude-fable-5-1": _MILLION,
@@ -30,6 +31,31 @@ CONTEXT_WINDOWS: dict[str, int] = {
 }
 
 
+#: Models a finding may name although no window is listed for them here: the
+#: OpenAI models Codex runs on, whose window Codex records itself. A model name
+#: is recorded text, so one outside this set and `CONTEXT_WINDOWS` is never
+#: printed (`cost/reasons.py`'s `_model_name`).
+OTHER_NAMED_MODELS: frozenset[str] = frozenset(
+    {
+        "gpt-5",
+        "gpt-5-codex",
+        "gpt-5-mini",
+        "gpt-5.1",
+        "gpt-5.1-codex",
+        "gpt-5.1-codex-max",
+        "gpt-5.1-codex-mini",
+        "gpt-5.2",
+        "gpt-5.2-codex",
+        "gpt-5.3-codex",
+        "gpt-5.3-codex-spark",
+        "gpt-5.4",
+        "gpt-5.4-mini",
+        "gpt-5.5",
+        "gpt-5.6",
+    }
+)
+
+
 def canonical_model(model: str) -> str:
     return _SNAPSHOT.sub("", model)
 

stacktrace/cost/output.py

@@ -0,0 +1,123 @@
+"""Output a response shows, where its record states less (ADR-0129).
+
+Claude Code writes a response one content block per record, each repeating its
+usage. Only the last record, the one with a stop reason, states the whole
+output; the ones before it state a part. OpenAIDR marks a response `final` only
+when it read that record, and calls output on any other a lower bound (its
+ADR-0014). Most sub-agent responses never get that record: on one machine 874
+of them recorded 9,907 output tokens and showed 105,802 in text and tool calls.
+
+So a response that is not final counts the greater of its recorded output and
+what its turns show: the characters of their text and of their tool calls'
+arguments as JSON, four to a token. On 425 final responses, whose output is
+exact, that count was never above the recorded output. A final response counts
+as recorded.
+
+A response's turns are its own session's, so this gives the same count before
+or after `cost.copies.distinct`. Only a count per response is kept, never text.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any, TypeVar, cast
+
+from stacktrace.cost.runs import UsageSession
+from stacktrace.sessions.protocols import ModelResponseLike
+
+S = TypeVar("S", bound=UsageSession)
+
+#: Characters a token, at least: calibrated on final responses, whose output
+#: is exact. Three was above the output on one of 425.
+CHARS_PER_TOKEN = 4
+
+
+def floored(sessions: Iterable[S]) -> tuple[S, ...]:
+    """The sessions in their order, each response that is not final counting
+    at least the output its turns show. A session none of whose responses
+    rises is returned as it is."""
+    return tuple(_floored(session) for session in sessions)
+
+
+def _floored(session: S) -> S:
+    unfinished = {r.response_id for r in session.responses if not r.final}
+    if not unfinished:
+        return session
+    shown = _shown(session, unfinished)
+    risen: dict[str, int] = {}
+    for response in session.responses:
+        floor = shown.get(response.response_id, 0) // CHARS_PER_TOKEN
+        if not response.final and floor > (response.usage.output_tokens or 0):
+            risen[response.response_id] = floor
+    if not risen:
+        return session
+    responses = tuple(
+        cast(ModelResponseLike, _Floored(r, risen[r.response_id])) if r.response_id in risen else r
+        for r in session.responses
+    )
+    return cast(S, _WithResponses(session, responses))
+
+
+def _shown(session: UsageSession, response_ids: set[str]) -> dict[str, int]:
+    """Characters each of these responses shows across its assistant turns.
+
+    A turn that issued tool calls shows their arguments: a reader stands a
+    placeholder in for the text of a record that holds only calls. Arguments
+    count as the model writes them, so a character outside ASCII is one, not
+    its escape."""
+    shown: dict[str, int] = {}
+    for turn in getattr(session, "turns", ()) or ():
+        response_id = getattr(turn, "response_id", None)
+        if response_id not in response_ids or getattr(turn, "role", None) != "assistant":
+            continue
+        calls = getattr(turn, "tool_calls", ()) or ()
+        if calls:
+            chars = sum(
+                len(json.dumps(call.arguments, ensure_ascii=False, default=str)) for call in calls
+            )
+        else:
+            chars = len(getattr(turn, "text", "") or "")
+        shown[response_id] = shown.get(response_id, 0) + chars
+    return shown
+
+
+class _WithResponses:
+    """A session whose responses count what they show: everything else is the
+    session's own."""
+
+    __slots__ = ("_session", "responses")
+
+    def __init__(self, session: UsageSession, responses: tuple[ModelResponseLike, ...]) -> None:
+        self._session = session
+        self.responses = responses
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._session, name)
+
+
+class _Floored:
+    """A response whose output is `output`: everything else is the response's
+    own, and it is still not final."""
+
+    __slots__ = ("_response", "usage")
+
+    def __init__(self, response: ModelResponseLike, output: int) -> None:
+        self._response = response
+        self.usage = _Output(response.usage, output)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._response, name)
+
+
+class _Output:
+    """Usage with output replaced: every other kind as recorded."""
+
+    __slots__ = ("_usage", "output_tokens")
+
+    def __init__(self, usage: Any, output: int) -> None:
+        self._usage = usage
+        self.output_tokens = output
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._usage, name)

stacktrace/cost/price_class.py

@@ -0,0 +1,48 @@
+"""A response's price class, named on its bucket's model (ADR-0130).
+
+Anthropic charges some responses more than their model's standard rate, and
+Fleet sees only bucket sums, so the client names the class:
+
+- `fast`: the response's `usage.speed` is `"fast"`.
+- `long`: its prompt is over its model's threshold. A prompt is input, cache
+  reads and cache writes.
+- `us`: its `usage.inference_geo` is `"us"`, US-only inference.
+
+`claude-haiku-5-5+long+us` is Haiku 5.5's long prompts run in the US. Each
+class is its own bucket, and Fleet prices it (Fleet ADR-0090). This module
+holds tokens only, never a price (ADR-0099).
+"""
+
+from __future__ import annotations
+
+from stacktrace.cost.tokens import Tokens
+from stacktrace.cost.weights import model_key
+from stacktrace.sessions.protocols import ModelResponseLike
+
+#: Joins a model and its qualifiers.
+SEPARATOR = "+"
+
+#: The prompt, in tokens, over which a model's responses cost more, keyed as
+#: `weights.model_key` keys a model. Anthropic's pricing page (read 2026-10-16)
+#: gives one: Claude Haiku 5.5, "for prompts over 100,000 tokens".
+LONG_PROMPT: dict[str, int] = {"claude-haiku-5-5": 100_000}
+
+
+def qualified(model: str, response: ModelResponseLike) -> str:
+    """`model` with its response's qualifiers, in a fixed order:
+    `claude-opus-5-5+fast`, `claude-haiku-5-5+long+us`. A value the API does
+    not document names no class, so Fleet prices it at the model's rate."""
+    found = [model]
+    if getattr(response, "speed", None) == "fast":
+        found.append("fast")
+    threshold = LONG_PROMPT.get(model_key(model))
+    if threshold is not None and Tokens.of(response.usage).context > threshold:
+        found.append("long")
+    if getattr(response, "inference_region", None) == "us":
+        found.append("us")
+    return SEPARATOR.join(found)
+
+
+def base_model(model: str) -> str:
+    """A model's name without its qualifiers."""
+    return model.split(SEPARATOR, 1)[0]

stacktrace/cost/reasons.py

@@ -50,7 +50,7 @@ from stacktrace.cost.measures import (
     repeats,
     window_share,
 )
-from stacktrace.cost.models import CONTEXT_WINDOWS, canonical_model
+from stacktrace.cost.models import CONTEXT_WINDOWS, OTHER_NAMED_MODELS, canonical_model
 from stacktrace.cost.runs import Run
 from stacktrace.cost.tokens import Tokens
 from stacktrace.sessions.protocols import ModelResponseLike, SessionLike, ToolCallLike
@@ -554,7 +554,8 @@ def _model_name(model_id: str) -> str:
     """A model as a finding may name it: one this release knows, by its own
     name, and anything else by a label of ours. The transcript's model field
     is recorded text (`test_untrusted_content_never_travels.py`)."""
-    return model_id if model_id in CONTEXT_WINDOWS else "a model this release does not list"
+    known = model_id in CONTEXT_WINDOWS or model_id in OTHER_NAMED_MODELS
+    return model_id if known else "a model this release does not list"
 
 
 def sustained_pace(judged: Judged) -> Reason:

stacktrace/cost/rules.py

@@ -47,6 +47,7 @@ from stacktrace.cost.reasons import lines as reason_lines
 from stacktrace.cost.runs import Run, as_of
 from stacktrace.detector.finding import NO_AGENT_KIND, Detection, Evidence, SessionRef, Severity
 from stacktrace.detector.rules import COST_RULES
+from stacktrace.sessions.entrypoint import programmatic
 from stacktrace.sessions.protocols import ModelResponseLike, SessionLike, TurnLike
 
 RUNAWAY_SESSION = "stacktrace-cost-runaway-session"
@@ -568,7 +569,7 @@ def runaway_session(
             ),
             *reason_lines(found, above[0]),
         ]
-        if main.entrypoint == "sdk-cli":
+        if programmatic(main.entrypoint):
             lines.append(("unattended", "started by a program, with nobody at the keyboard"))
         firings.append(_firing(RUNAWAY_SESSION, main, turn, above, lines, context.placements))
     return tuple(firings), tuple(misses)