stacktrace-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{stacktrace_cli-0.2.0 → stacktrace_cli-0.2.1}/CLAUDE.md

@@ -11,8 +11,8 @@ and by CI pipelines that invoke `stacktrace`, and it builds on the open-source
 It is also the **design home for Stacktrace Detect** — the AIDR product this CLI
 grows into. The specs in `docs/specs/` and the decisions in `docs/adrs/` describe
 the whole system: session input, correlation against the composition graph, the
-three-stage detector, and the combined report. The code here is the placeholder that
-precedes them.
+three-stage detector, and the combined report. The code here implements them
+incrementally.
 
 ## Common commands
 
@@ -52,11 +52,13 @@ the single source of truth for the version string reported by `--version`.
 
 Build backend is hatchling with a src layout; the wheel's contents are declared
 explicitly by `[tool.hatch.build.targets.wheel] packages = ["src/stacktrace_cli"]`.
-The only runtime dependency is `openaca>=0.4.0`, which supplies the Agent
-Composition Analysis primitives this CLI is intended to drive.
+Runtime dependencies are `openaca` for the Agent Composition Analysis
+primitives this CLI drives, `openaidr` for session collection, and `httpx` for
+the remote channel. Each is pinned exactly before a release; see
+`docs/cutover-openaca-remote.md`.
 
-The package is currently pre-alpha: `main()` reports its version and points at
-the docs. Real functionality lands in later releases.
+`sessions`, `detect`, `monitor` and `remote` are native; `bom`, `policy` and
+`scan` are OpenACA's own command objects.
 
 **The design that functionality implements is in this repo.** Read
 `docs/specs/aidr.md` first — it is the umbrella: components, contracts, the two
@@ -121,6 +123,25 @@ nothing about detection.
   a review names a site, fix the invariant and extend the exhaustive test — a
   second finding of the same class means the first fix was at the wrong level.
 
+## Adding a command
+
+A command is a **pass-through** or it is **native**, never both — and a
+pass-through never gains a flag of its own. See
+[ADR-0021](docs/adrs/0021-two-command-kinds.md) for why.
+
+- **Pass-through** — add one string to `PASSTHROUGH` in
+  `src/stacktrace_cli/cli.py`, having decided it belongs. The loop registers
+  OpenACA's own command object under that name; there is nothing else to
+  write and nothing to keep in step with OpenACA.
+- **Native** — write a Click command or group and `add_command` it, the way
+  `remote` is. If it needs OpenACA it calls `openaca.core`
+  ([ADR-0020](docs/adrs/0020-openaca-consumption-boundary.md)), and whatever
+  it names there is added to the contract test in `tests/remote/`, because it
+  now holds duplicated knowledge of an interface.
+
+The section a command lands under in `--help` follows from which kind it is;
+there is no second list to update.
+
 ---
 
 ## Behavioral guidelines

stacktrace_cli-0.2.1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: stacktrace-cli
+Version: 0.2.1
+Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
+Project-URL: Homepage, https://stacktrace.ai
+Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
+License-Expression: LicenseRef-Proprietary
+Keywords: agent-security,ai-security,openaca,stacktrace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx<1.0.dev0,>=0.28.1
+Requires-Dist: openaca==0.6.0
+Requires-Dist: openaidr==0.1.0
+Description-Content-Type: text/markdown
+
+# stacktrace-cli
+
+Detection and response for AI coding agents, from the command line.
+
+Coding agents read files, run shell commands and call MCP servers on their own
+initiative, and they write a transcript of every bit of it to disk.
+`stacktrace` reads those transcripts, correlates what ran against the
+components the agent is built from, and reports the security and reliability
+findings in it — locally, on the machine the agent worked on.
+
+The PyPI distribution is `stacktrace-cli`; the command it installs is
+`stacktrace`. The two names differ because the bare `stacktrace` name on PyPI
+belongs to an unrelated project.
+
+## Installation
+
+```bash
+uv tool install stacktrace-cli     # isolated; recommended
+# or
+pip install stacktrace-cli
+```
+
+Requires Python 3.11 or newer.
+
+```console
+$ stacktrace --version
+stacktrace 0.2.1 (openaca 0.6.0)
+```
+
+## Quick start
+
+```bash
+stacktrace sessions      # what the agents on this machine did
+stacktrace detect        # what is wrong with it
+stacktrace monitor       # the same, live in a browser
+```
+
+## Commands
+
+| Command | |
+|---|---|
+| `sessions` | Print what the agents on this machine actually did. |
+| `detect` | Find security and reliability findings in what agents did. |
+| `monitor` | Watch this machine's agents in a browser, live. |
+| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
+| `scan` | Scan a repository or endpoint for agent-composition findings. |
+| `bom` | Generate an Agent BOM for a repository or endpoint. |
+| `policy` | Validate and compile restrictive endpoint policies. |
+
+The last three are composition analysis, supplied by
+[`openaca`](https://pypi.org/project/openaca/) and available under either
+name.
+
+## What it looks like
+
+```console
+$ stacktrace sessions --since 2d --include-content
+claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
+  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  assistant: Filing the release-notes follow-up.
+                        -  github/create_issue
+
+Summary — 1 sessions, 2 turns, 2 tool calls
+
+  agent kinds
+          1  claude-code
+
+  tools called (2 distinct)
+          1  Read
+          1  github/create_issue
+
+  MCP servers reached (1 distinct)
+          1  github
+
+  0 subagent turns · 0 results abridged upstream · 1 ok
+
+1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
+```
+
+A blank status column is the collector's `unknown`, not a pending call: the
+client recorded no outcome that could be established, and the closing line
+counts those rather than filling one in.
+
+## What `detect` finds
+
+Four kinds of finding, under two families that carry separate severity
+ladders — a stalled loop and a leaked credential do not belong on one scale.
+
+**Security** — a credential reaching an outbound call; an injected instruction
+the agent then followed; a vulnerable component actually reached, with the
+vulnerability behind it.
+
+**Reliability** — a loop that stalled; a call that hung.
+
+Findings are correlated against an Agent BOM before they are judged, so a
+vulnerable component is reported when something actually used it rather than
+because it is installed.
+
+## What leaves your machine
+
+Two of `detect`'s three stages run entirely locally and need no model or
+credential. The third sends flagged sessions to the agent's *own* CLI — the
+provider that produced the transcript, never a different one — capped by
+`--budget`; `--no-escalate` turns it off and leaves the two local stages.
+
+`sessions` omits prompts, tool arguments and results unless you pass
+`--include-content`. `monitor` binds to loopback only, refuses a non-loopback
+address rather than warning about it, and escalates nothing unless `--escalate`
+is given.
+
+## Status
+
+Beta, and under active development.
+
+`sessions`, `detect` and `monitor` work end to end today. Session collection
+currently reads Claude Code transcripts; further agent kinds are in progress
+upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+
+## Built on
+
+Two Apache-2.0 packages, neither of which depends on this one:
+[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
+and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.
+
+## Licence
+
+Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)

stacktrace_cli-0.2.1/README.md

@@ -0,0 +1,129 @@
+# stacktrace-cli
+
+Detection and response for AI coding agents, from the command line.
+
+Coding agents read files, run shell commands and call MCP servers on their own
+initiative, and they write a transcript of every bit of it to disk.
+`stacktrace` reads those transcripts, correlates what ran against the
+components the agent is built from, and reports the security and reliability
+findings in it — locally, on the machine the agent worked on.
+
+The PyPI distribution is `stacktrace-cli`; the command it installs is
+`stacktrace`. The two names differ because the bare `stacktrace` name on PyPI
+belongs to an unrelated project.
+
+## Installation
+
+```bash
+uv tool install stacktrace-cli     # isolated; recommended
+# or
+pip install stacktrace-cli
+```
+
+Requires Python 3.11 or newer.
+
+```console
+$ stacktrace --version
+stacktrace 0.2.1 (openaca 0.6.0)
+```
+
+## Quick start
+
+```bash
+stacktrace sessions      # what the agents on this machine did
+stacktrace detect        # what is wrong with it
+stacktrace monitor       # the same, live in a browser
+```
+
+## Commands
+
+| Command | |
+|---|---|
+| `sessions` | Print what the agents on this machine actually did. |
+| `detect` | Find security and reliability findings in what agents did. |
+| `monitor` | Watch this machine's agents in a browser, live. |
+| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
+| `scan` | Scan a repository or endpoint for agent-composition findings. |
+| `bom` | Generate an Agent BOM for a repository or endpoint. |
+| `policy` | Validate and compile restrictive endpoint policies. |
+
+The last three are composition analysis, supplied by
+[`openaca`](https://pypi.org/project/openaca/) and available under either
+name.
+
+## What it looks like
+
+```console
+$ stacktrace sessions --since 2d --include-content
+claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
+  assistant: Reading the changelog before drafting the release notes.
+    ok                28c  Read
+        result: ## 0.4.0 - correlate, detect
+  assistant: Filing the release-notes follow-up.
+                        -  github/create_issue
+
+Summary — 1 sessions, 2 turns, 2 tool calls
+
+  agent kinds
+          1  claude-code
+
+  tools called (2 distinct)
+          1  Read
+          1  github/create_issue
+
+  MCP servers reached (1 distinct)
+          1  github
+
+  0 subagent turns · 0 results abridged upstream · 1 ok
+
+1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
+```
+
+A blank status column is the collector's `unknown`, not a pending call: the
+client recorded no outcome that could be established, and the closing line
+counts those rather than filling one in.
+
+## What `detect` finds
+
+Four kinds of finding, under two families that carry separate severity
+ladders — a stalled loop and a leaked credential do not belong on one scale.
+
+**Security** — a credential reaching an outbound call; an injected instruction
+the agent then followed; a vulnerable component actually reached, with the
+vulnerability behind it.
+
+**Reliability** — a loop that stalled; a call that hung.
+
+Findings are correlated against an Agent BOM before they are judged, so a
+vulnerable component is reported when something actually used it rather than
+because it is installed.
+
+## What leaves your machine
+
+Two of `detect`'s three stages run entirely locally and need no model or
+credential. The third sends flagged sessions to the agent's *own* CLI — the
+provider that produced the transcript, never a different one — capped by
+`--budget`; `--no-escalate` turns it off and leaves the two local stages.
+
+`sessions` omits prompts, tool arguments and results unless you pass
+`--include-content`. `monitor` binds to loopback only, refuses a non-loopback
+address rather than warning about it, and escalates nothing unless `--escalate`
+is given.
+
+## Status
+
+Beta, and under active development.
+
+`sessions`, `detect` and `monitor` work end to end today. Session collection
+currently reads Claude Code transcripts; further agent kinds are in progress
+upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).
+
+## Built on
+
+Two Apache-2.0 packages, neither of which depends on this one:
+[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
+and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.
+
+## Licence
+
+Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)

stacktrace_cli-0.2.1/docs/cutover-openaca-remote.md

@@ -0,0 +1,87 @@
+# The openaca 0.6.0 cutover
+
+Moved out of `README.md`, which is the PyPI long description and therefore a
+public page: this is operator and maintainer detail for a private repository.
+
+## Dependency resolution
+
+Both `openaca` and `openaidr` resolve from PyPI now, like any other
+dependency — no sibling checkout, no `[tool.uv.sources]` override. What still
+gates a release is narrower: both float on `>=` during normal development but
+must be pinned exactly (`==`) before a version is published, so a built wheel
+names precisely what it was tested against.
+`uv run pytest tests/test_release_readiness.py -m release_gate` checks that —
+the `release-stacktrace` skill runs it as part of cutting a release.
+
+
+## Cutover from `openaca remote`
+
+`stacktrace remote` is the hosted-service client OpenACA is removing. The
+behaviour, the payload and the Cloud endpoints are unchanged; only the code
+that produces them moved. Machines already running `openaca remote sync
+endpoint` need four steps each.
+
+1. **Have the collector token to hand, or mint a new one.** A collector token
+   cannot be recovered from the Cloud — it is returned once at issuance and
+   only a hash and its last four characters are kept — so it has to come from
+   wherever it was stored (an MDM secret store, a password manager). If it was
+   not stored, mint a new one and deploy that; nothing goes down while you do,
+   because the existing token keeps working until it is revoked.
+2. **Configure this machine.** `stacktrace remote configure --token …`, or set
+   `STACKTRACE_REMOTE_TOKEN` and `STACKTRACE_REMOTE_API_URL` for a scripted
+   deployment.
+3. **Repoint whatever schedules the sync** at `stacktrace remote sync
+   endpoint`.
+4. **Delete `~/.config/openaca/remote.toml`.** Once OpenACA has no `remote`
+   command, that file is an unused plaintext credential sitting on disk.
+   Nothing breaks if it stays, which is exactly why it will be forgotten.
+
+### What takes care of itself
+
+- **The asset converges.** Registration is idempotent on `(org, asset_type,
+  external_id)` with the host name as `external_id`, so registering from here
+  resolves to the same asset OpenACA registered — one extra round trip on the
+  first run, no duplicate machine in the console.
+- **Both commands may coexist during the overlap**, producing two BOM rows per
+  sync. That is noise rather than corruption.
+
+> These two statements, and the unrecoverability of a collector token in step
+> 1, describe what the deployed Cloud does. They have **not** been confirmed
+> against the running service for this release — they are read from the
+> hosted side's design, which records what some revision implements rather
+> than what production does today. Confirm them before an operator acts on
+> step 1 in particular: discarding the only copy of a token on the strength of
+> an unverified sentence leaves no recovery.
+
+### What does not
+
+- **A pending OpenACA spool is orphaned.** Its files are in
+  `~/.local/state/openaca`, and this channel never reads them. Drain it by
+  running the old command once before cutting over, or accept losing what it
+  holds. Do not assume that is one sync's worth: the spool keeps one file per
+  failed agent and accumulates across offline runs, so count the files first.
+- **The MDM deploy scripts and the scheduled agent** do not exist here yet.
+
+## Release obligations
+
+Finishing the remote-sync work was **not** the same as being releasable, and
+the gap was structural rather than a matter of polish: while `pyproject.toml`
+carried a path source to a sibling checkout, `pip install stacktrace-cli` from
+PyPI would have resolved an `openaca` without the consumption facade, and every
+`remote` command would have failed at import.
+
+All three are discharged, at `openaca` 0.6.0 — the first release carrying the
+facade:
+
+1. `[tool.uv.sources]` is gone; `uv.lock` resolves `openaca` from PyPI.
+2. `.github/workflows/ci.yml` checks out this repository alone. The sibling
+   checkout and its pinned-revision assertion went with the path source.
+3. The floor is `openaca>=0.6.0`, which is where plan 005 Task 1's
+   required-import probe first reports no missing name. Re-run that probe
+   against any candidate release before moving the floor again; it passes only
+   when it reports nothing missing.
+
+One proof retired with them. The payload-equivalence test imported openaca's
+`tools.remote` — the module 0.6.0 removed — so it cannot run against any
+release that carries the facade. What it established is a fact about the
+migration, not a property that a later release could re-check.

stacktrace_cli-0.2.1/docs/releases/v0.2.1.md

@@ -0,0 +1,49 @@
+# 0.2.1 — the page in front of the CLI
+
+For a distribution, the PyPI listing is the product surface a reader meets
+first. This release treats it as one. Nothing about what `stacktrace` does
+changes here — no command, flag, rule or output shape moves — and the whole
+delta is what the page in front of it claims.
+
+## Highlights
+
+- **The package metadata describes the product rather than a placeholder.**
+  The summary line said "Placeholder CLI for Stacktrace.ai — installs the
+  `stacktrace` command", written when that was true and left standing after
+  0.1.0 and 0.2.0 made it false. It now says what the CLI is for. Authorship
+  moves from an individual to Stacktrace AI, Inc., and
+  `Development Status :: 2 - Pre-Alpha` becomes `4 - Beta`, matching the
+  README's own Status section rather than contradicting it two clicks away.
+  `Operating System :: OS Independent` and per-minor Python classifiers for
+  3.11, 3.12 and 3.13 are added, so PyPI's own filters can find the package
+  under the versions `requires-python` already accepted.
+
+- **The README is written for someone deciding whether to install.** It was a
+  contributor's design document — Design, Adding a command, Development,
+  Release obligations — that happened to be the `readme` field, so the long
+  description on PyPI opened by explaining the repository to people who
+  already had it checked out. It now opens with what the tool does in three
+  sentences and continues into install, a three-command quick start, the
+  command table, real sample output, what `detect` finds, and what leaves your
+  machine. That last section is the one a security reader arrives looking for
+  and previously had to infer.
+
+- **The contributor material moved rather than being deleted.** The design and
+  workflow content is in `CLAUDE.md`, and the openaca 0.6.0 cutover notes and
+  release obligations are in `docs/cutover-openaca-remote.md`. Both stay in the
+  repository and neither is in the wheel.
+
+## Install
+
+`uv tool install stacktrace-cli==0.2.1` or `pip install stacktrace-cli==0.2.1`.
+
+## Compatibility
+
+Nothing to do. This release changes no behaviour: the CLI's commands, flags,
+output and upload payloads are identical to 0.2.0, and an existing install has
+no reason to upgrade beyond the version string.
+
+One note on the `Development Status :: 4 - Beta` classifier. It is a claim
+about the project's stage, not a back-compat promise — the terms 0.2.0 shipped
+under still hold, and interfaces can still change between releases without a
+deprecation window.

{stacktrace_cli-0.2.0 → stacktrace_cli-0.2.1}/pyproject.toml

@@ -1,21 +1,25 @@
 [project]
 name = "stacktrace-cli"
-version = "0.2.0"
-description = "Placeholder CLI for Stacktrace.ai — installs the `stacktrace` command."
+version = "0.2.1"
+description = "CLI for Stacktrace — Detection and Response platform for AI Agents."
 readme = "README.md"
 requires-python = ">=3.11"
 # Proprietary (ADR-0007). The two dependencies are Apache-2.0; this package is
 # not, and must never inherit their licence by omission. SPDX LicenseRef- is
 # the expression form for a licence with no public identifier.
 license = "LicenseRef-Proprietary"
-authors = [{ name = "Prasanth G", email = "prasanth@openaca.dev" }]
+authors = [{ name = "Stacktrace AI, Inc", email = "founders@stacktrace.ai" }]
 keywords = ["stacktrace", "openaca", "ai-security", "agent-security"]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 4 - Beta",
     "License :: Other/Proprietary License",
     "Environment :: Console",
     "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Security",
 ]
 dependencies = [

stacktrace_cli-0.2.1/src/stacktrace_cli/__init__.py

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

{stacktrace_cli-0.2.0 → stacktrace_cli-0.2.1}/uv.lock

@@ -690,7 +690,7 @@ wheels = [
 
 [[package]]
 name = "stacktrace-cli"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },