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

{stacktrace_cli-0.1.0 → stacktrace_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Placeholder CLI for Stacktrace.ai — installs the `stacktrace` command.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: Prasanth G <prasanth@openaca.dev>

{stacktrace_cli-0.1.0 → stacktrace_cli-0.2.0}/docs/adrs/0006-trust-boundary-and-detection-upload.md

@@ -5,7 +5,7 @@ status: accepted
 date: 2026-08-28
 supersedes: null
 superseded-by: null
-amended-by: 0011
+amended-by: 0011, 0027
 ---
 
 ## Context

{stacktrace_cli-0.1.0 → stacktrace_cli-0.2.0}/docs/adrs/0008-console-in-separate-demo-package.md

@@ -1,10 +1,10 @@
 ---
 id: 0008
 title: Ship the local trace console as a separate demo package
-status: accepted
+status: superseded
 date: 2026-08-27
 supersedes: null
-superseded-by: null
+superseded-by: 0026
 ---
 
 ## Context

stacktrace_cli-0.2.0/docs/adrs/0026-the-console-becomes-a-product-surface.md

@@ -0,0 +1,108 @@
+---
+id: 0026
+title: The console becomes a product surface, served by the engine
+status: accepted
+date: 2026-09-06
+supersedes: 0008
+superseded-by: null
+amends: null
+amended-by: null
+---
+
+## Context
+
+ADR-0008 kept the trace console out of the engine and gave three reasons. Two
+were about *kind*: a served page with taste-driven layout is different software
+from a library, and their release cadences and review standards differ. One was
+about *order*: making the console the product surface "before the engine's
+claims are validated inverts the order — the engine comes first, and nothing yet
+measures its central claim."
+
+That last reason names its own expiry, and it has arrived. 0.1.0 ships
+`sessions`, `detect` over nine rules and three stages, and both upload paths;
+the detector's claims are measured by its own corpus and by the hosted side
+receiving them. The engine came first, and did.
+
+What forces the decision now is a product one rather than a technical one: the
+data is only useful if a person can follow it, and a sequence reads better as a
+timeline than as a findings list — 0008's own opening sentence. A developer who
+has to run `detect`, read JSON, and re-run it to see what changed is being asked
+to be the renderer. `stacktrace monitor` is that renderer, and it has to ship
+where the data is.
+
+## Decision
+
+The engine serves a local console. `stacktrace monitor` starts an HTTP server
+bound to loopback, opens a browser, and renders live sessions and detections
+from in-process calls into the same surfaces `detect` uses.
+
+The three clauses of 0008 that this reverses, stated plainly:
+
+1. **The engine gains a serving surface and a browser-facing asset.** `site/`
+   ships as package data in the wheel.
+2. **The console performs no analysis of its own.** *This one survives.* Monitor
+   calls `collect_sessions`, `acquire_correlated_view` and `run_detector`; it
+   adds no rule, no grade and no heuristic, and it never writes the verdict
+   cache. A finding on the page is a finding `detect` would print.
+3. **The tenets govern the console now**, because it is a product surface rather
+   than a demonstration. Trust, quality, cost and security apply — which is why
+   the page computes only the two free stages by default, and why the one action
+   it offers is gated four ways.
+
+## Alternatives considered
+
+- **Keep 0008 and ship the console as a separate optional distribution**
+  (`stacktrace-console`, or an extra) — rejected. It preserves the letter of
+  0008 at the cost of the thing 0008 was protecting: a second distribution has
+  its own version, its own install step and its own drift against three read
+  contracts, and every user who wants to *see* their data pays an install to do
+  it. The cadence argument that justified separation for a demo does not survive
+  the surface becoming the product.
+
+- **Amend 0008 to carve out one read-only local surface** — rejected as
+  dishonest bookkeeping. The carve-out is the whole of clause 1; an amendment
+  that removes a decision's first clause is a supersession wearing a smaller
+  word.
+
+- **Leave rendering to the hosted console** — rejected. The hosted side is
+  agent-scoped and receives only what ADR-0006 authorizes: no prompt, no
+  argument, no result, no matched value. The local console is precisely where a
+  responder may see the matched string, which ADR-0006 calls out as deliberate
+  asymmetry. A fleet view cannot replace a machine view; it is a different
+  question.
+
+- **Ship the console but compute nothing** (render the last `detect` run's
+  cache) — rejected. "Live sessions, stale findings" is the failure mode a
+  reader cannot see: the page looks current, and a leak that happened after the
+  last run is absent from it.
+
+## Consequences
+
+**What this enables.** A developer watches an alias resolve into a real
+component while a session is still running — 0008's own description of the
+demonstration, now available without a demo. The three published read contracts
+gain their first in-repo consumer, so a change to span identity breaks a test
+here rather than silently landing enrichments on the wrong rows elsewhere.
+
+**What it costs, and 0008 was right about both.**
+
+- **Every consumer of the wheel carries a UI they did not ask for.** `site/` is
+  three files and no JavaScript dependency, so the cost is bytes rather than a
+  dependency tree — but a library consumer still ships them.
+- **Visual iteration now happens inside the engine's release process.** A
+  layout change rides a release built for a detection engine. The mitigation is
+  that the console's own priorities stay 0008's — latency, then fidelity — and
+  that no page change can alter a finding, because monitor computes none.
+
+**What to watch for.** A rule that fires only in the console, or a grade the
+page adjusts for legibility. Either would make clause 2 false, and clause 2 is
+the one keeping this from being a fork of the detector.
+
+## When to revisit
+
+Revisit if the console acquires a reason to compute something the detector does
+not — that is the point at which it stops being a renderer and needs its own
+decision. Revisit if the wheel's browser-facing assets grow beyond static files,
+because a build step is the cadence problem 0008 warned about actually arriving.
+Do not revisit on the grounds that a library consumer carries the UI: that cost
+is accepted here explicitly, not overlooked.

stacktrace_cli-0.2.0/docs/adrs/0027-a-finding-may-name-what-it-could-not-place.md

@@ -0,0 +1,112 @@
+---
+id: 0027
+title: A finding may name the component it could not place
+status: accepted
+date: 2026-09-07
+supersedes: null
+superseded-by: null
+amends: 0006
+---
+
+## Context
+
+ADR-0006 constraint 3 keeps session content off the wire *by construction*: a
+detection carries a rule id and non-content descriptors, "never an excerpt of
+an argument, result or prompt", and the family is uploadable whole so no
+projection exists to be got wrong. That constraint has held every finding this
+product has shipped and is not in question here.
+
+One case has now met the condition ADR-0006 wrote for its own revision:
+
+> Revisit if a detection type proves genuinely unactionable without an evidence
+> excerpt — that would be a real argument against constraint 3, and the answer
+> is more likely a better non-content descriptor than an excerpt.
+
+A finding's **subject** is what the finding is about. Where correlation places
+the call, the subject is a BOM component and constraint 3 was never in play.
+Where correlation cannot place it, the only name that exists is the one the
+session used — `call.mcp_server` for a server, `arguments["skill"]` for a
+skill — and the second of those is, read literally, an excerpt of an argument.
+
+Removing it leaves the highest-severity finding this detector produces reading:
+
+    high  stacktrace-credential-egress
+          Credential-shaped material reached an outbound call
+          on a mcp_server (not in inventory)
+
+A responder cannot act on that. They cannot rotate the right credential, revoke
+the right access, or find the thing, because the document does not say what the
+thing was. The unplaced case is also the one where naming matters *most*: a
+credential reaching a component no Agent BOM declares is the least expected and
+least explicable event this product reports.
+
+Empirically it is not rare. On the machine this was written against, 156 calls
+across 15 distinct names were unplaced, including the one `high`
+credential-egress finding in the window.
+
+## Decision
+
+**A detection may carry the name the session addressed a component by, when
+correlation could not place it.** This narrows ADR-0006 constraint 3; every
+other clause of 0006 stays in force, and constraint 3 continues to forbid
+excerpts of prompts, results and arguments in every other position.
+
+Four bounds make it a descriptor rather than an opening.
+
+1. **One field, one purpose.** The name appears only as
+   `Participant.name` on a finding's subject or a named party to it. No rule
+   may interpolate it into prose; `Evidence.detail` remains closed to it, which
+   is the drift ADR-0006 names as *"reached by writing a helpful sentence"*.
+
+2. **It is never an identity.** `Participant.identity` stays null for an
+   unplaced party, so the name can resolve no lookup, join to no inventory and
+   render as no link. A consumer must mark it as unverified. Two machines can
+   call unrelated servers `support`; this ADR does not make that name mean
+   anything beyond the session that said it.
+
+3. **Bounded and validated at the boundary.** Length-capped on the wire, and
+   walked by the same disclosure gate every other leaf passes, so a name
+   carrying a path or a credential shape is refused rather than trimmed.
+
+4. **The local surfaces are unchanged and remain the fuller answer.** `monitor`
+   and `stacktrace detect` read the session directly and may always say more
+   than the upload does. This ADR is only about what leaves the machine.
+
+## Consequences
+
+The `credential-egress` above reads `on support (not in inventory)`, in Fleet
+as well as locally, and a responder has somewhere to start.
+
+The residual exposure is a short, model-influenceable string reaching a hosted
+service. It is real and it is accepted here rather than argued away: an
+attacker who can choose the `skill` argument already drives the agent's tool
+calls, and has channels with far more bandwidth than a capped name field in a
+detection upload. What this ADR must not become is precedent — the argument
+above is about *the subject of a finding being unnameable otherwise*, and does
+not extend to any other field.
+
+`tests/test_untrusted_content_never_travels.py` keeps every other canary,
+including the ones for prompts, results, arguments and the tool name an MCP
+server chose. It gains the case this ADR permits, so the exemption is stated
+where the invariant is enforced rather than only here.
+
+## Alternatives rejected
+
+- **Drop the name, keep the type** (`a skill (not in inventory)`). This was
+  implemented and is what prompted the ADR. It is compliant and unactionable,
+  which makes it the wrong trade for a product whose output is meant to be
+  acted on. A rule that produces findings nobody can use protects nothing.
+
+- **Carry the server alias, drop the skill argument.** Defensible on the letter
+  of constraint 3 — a server alias is not an argument excerpt — and rejected as
+  a distinction a reader cannot see. It would make one finding nameable and its
+  neighbour not, for a reason invisible on the page, and leaves the same
+  residual exposure for the case it permits.
+
+- **Send a hash of the name.** Rejected. It is stable across machines, which is
+  the one property the name must not have, and it is unreadable, which is the
+  one property a responder needs.
+
+- **Amend nothing and surface the name only in `monitor`.** Rejected as the
+  status quo restated: triage happens in Fleet, and a console on one laptop
+  does not answer for a fleet.

{stacktrace_cli-0.1.0 → stacktrace_cli-0.2.0}/docs/adrs/INDEX.md

@@ -41,7 +41,7 @@ supersedes anything yet.
 - [0005](0005-detection-family-and-report-assembly.md) — **Detections are their own finding family, assembled here.** Why a detection is not an observation, and why `stacktrace` merges the four families rather than OpenACA emitting a fourth. `stacktrace-*` identifiers. Read before adding a finding family, touching output assembly, or contributing anything upstream.
 - [0006](0006-trust-boundary-and-detection-upload.md) — **Sessions never leave the machine; detections upload agent-keyed.** No upload path for anything session-derived; findings carry descriptors, never excerpts; place identity stays in the envelope. Read before adding a detection field, touching redaction, or describing AIDR as fully local or anonymous.
 - [0007](0007-proprietary-package-on-open-dependencies.md) — **Proprietary package on open dependencies.** Why this is not inside OpenACA or OpenAIDR, and why the dependency arrow never reverses. Read before moving code between repos.
-- [0008](0008-console-in-separate-demo-package.md) — **Trace console ships as a separate demo package.** Read before adding a served UI, transport, or web asset to this repo.
+- [0008](0008-console-in-separate-demo-package.md) — **Trace console ships as a separate demo package.** Read before adding a served UI, transport, or web asset to this repo. **Superseded by [0026](0026-the-console-becomes-a-product-surface.md).**
 - [0010](0010-detection-severity-and-confidence-ladders.md) — **Detections define their own severity and confidence ladders.** Amends ADR-0005: `openaca.core` exports no ladder to reuse, and CVSS labels grade advisories a detection does not have. Read before changing a finding's grade, or before assuming the four families share one scale.
 - [0011](0011-verdict-cache.md) — **A bounded local verdict cache, and what it may hold.** Amends ADR-0006: a reasoning verdict is an expensive pure function of a session, so it may persist — carrying rule ids, grades, spans and analyzer identity, and never conversation. Read before persisting anything session-derived, or before letting an upload path read local state.
 - [0012](0012-observation-evidence-kinds-and-transport.md) — **Observation is graded by what could misread it; an MCP transport is positive-only evidence.** Severity and confidence are orthogonal and neither is read off the other; a precondition sets a finding's grade, corroboration takes the best; `stdio` is never evidence of local execution. Read before changing a rule's confidence, adding an evidence kind, or treating an absent transport as local.
@@ -57,4 +57,6 @@ supersedes anything yet.
 - [0022](0022-detection-scope-is-a-catalogue-column.md) — **Detection scope is a per-rule catalogue column, set by cardinality.** Fleet identifies a detection by rule plus anchor, so scope decides what counts as the same finding seen again; `advisory-reach` and `progress-stall` both read as session-shaped and fire more than once per session, and session scope would merge those firings into one row permanently. Deriving scope from `bool(evidence)` is rejected — every rule always cites something. Read before adding a rule, or before changing how one groups its findings.
 - [0023](0023-sync-detect-collects-and-does-not-escalate.md) — **`sync detect` re-collects in-process, and defaults `--escalate` off.** The inverse of `stacktrace detect`, because a scheduled unattended run spending provider quota and crossing a content boundary on a timer is a recurring charge nobody approved per-run; consuming `detect --format json` was rejected as a projection of a projection. Read before changing a sync default, or before aligning the two commands' flags.
 - [0024](0024-the-upload-carries-observations.md) — **The upload carries observations; the Cloud derives catalogue text and coverage.** `title`, `remediation`, `family`, `verdict.stage` and `coverage` are all dropped — the first four are catalogue facts the Cloud seeds, and coverage is summed from `activity[]`. Not a privacy projection (ADR-0006 settled that) but a non-duplication one. Read before adding a field to the upload payload, or before "fixing" a bare `rule_id` in the console.
+- [0026](0026-the-console-becomes-a-product-surface.md) — **The console becomes a product surface, served by the engine.** Supersedes ADR-0008 on its own stated condition: the engine came first, 0.1.0 shipped, and the data is only useful if a person can follow it. `stacktrace monitor` serves a loopback page from in-process calls, so the wheel now carries a `site/` asset — the cost 0008 refused, accepted here explicitly. What survives from 0008 is the clause that matters: the console renders and never computes, so a finding on the page is one `detect` would print. Read before adding anything to the console that the detector does not produce.
 - [0025](0025-a-denied-call-is-activity-never-an-invocation.md) — **A denied call is activity, and never an invocation.** ADR-0017 makes a declined repeat a stall while `outcome.py` keeps a denied call out of every count, so a denied-only session produced a finding with no activity and the Cloud rejected the whole run; a separate `denied` counter resolves it without either rule bending, and coverage keeps summing `invocations` alone. Read before changing what `activity[]` counts, or before folding `denied` into a coverage-like ratio.
+- [0027](0027-a-finding-may-name-what-it-could-not-place.md) — **A finding may name the component it could not place.** Narrows ADR-0006 constraint 3 for one field: an unplaced subject carries the name the session addressed it by, never as an identity. Read before removing a name from a finding on trust-boundary grounds, or before widening this to a second field.

{stacktrace_cli-0.1.0 → stacktrace_cli-0.2.0}/docs/plans/007-detection-upload.md

@@ -48,7 +48,7 @@ not against the spec's prose. Four of them contradict the obvious reading.
 | The Cloud's bounds | read `stacktrace-fleet` `schemas.py` | `MAX_DETECTIONS=5000`, `MAX_UNKNOWNS=5000`, `MAX_ACTIVITY=20000`, `MAX_EVIDENCE_PER_DETECTION=100`, `MAX_COMPONENTS_PER_DETECTION=50`, `MAX_CAPABILITIES=16`, `MAX_SPANS_PER_UNKNOWN=100`, `MAX_SPAN_LEN=256`, `MAX_SESSION_ID_LEN=256`, `MAX_STRING_LEN=512`, `MAX_RULE_ID_LEN=128` |
 | The span grammar | read `stacktrace-fleet` `schemas.py` | `^[a-z0-9][a-z0-9._-]*(?::[A-Za-z0-9._-]+)+:[0-9]+$`, and separately: a span may carry no path separator at all |
 | The response shape | read `DetectRunResponse` | `detect_run_id`, `agent_id`, `detections_ingested`, `detections_new`, `activity_rows`, `dashboard_url` |
-| `Composition` has no instance id | read `composition.py`, `acquire.py` | `acquire` reads only `openaca:agent_kind`; there is no field to carry `openaca:agent_id` |
+| `Composition` has no instance id | read `composition.py`, `acquire.py` | `acquire` read only `openaca:agent_kind` and there was no field to carry `openaca:agent_id`. Closed by [#12](https://github.com/stacktrace-ai/stacktrace/issues/12): `Composition.agent_instance_id`, read by the shared `root_property` walk |
 | The spool is single-kind in four places | read `spool.py` | `pending-bom-` is a literal at four sites and `replay_pending_uploads` calls `upload_bom` directly |
 
 **ADRs:** the decisions this plan rests on are accepted and indexed —
@@ -274,16 +274,21 @@ rewrite*.
 
 ## Task 9: The cross-repo gate
 
-**Files:** none in this repository.
+**Files:** `tests/remote/test_detect_payload_reaches_the_cloud_model.py`.
 
 - [ ] **Step 1: `denied` needs the Cloud's half.** The producer emits it per the
   spec; `RuntimePayload` is `extra="forbid"` (ground truth row 7), so until
   `stacktrace-fleet` ships the counter split, an upload is a 422 for the whole
   agent's run. `--dry-run` is unaffected. Specified in
   `stacktrace-fleet/docs/specs/2026-09-05-denied-attempts-and-agent-runtime.md`.
-- [ ] **Step 2: Add a contract test that fails when the gate clears**, in the
-  shape `test_openaca_contract.py` already uses, so the coupling is visible
-  here rather than discovered by a 422 in the field.
+  The sibling checkout now accepts the whole shape; the *deployed* service has
+  not been checked, so this stays open until it has.
+- [x] **Step 2: Add a contract test over the real payload**, in the shape
+  `test_openaca_contract.py` already uses, so the coupling is visible here
+  rather than discovered by a 422 in the field. It runs the payload
+  `build_detect_payloads` and `activity_for_upload` actually produce — `mcp`,
+  `denied`, `subject`, `involved` and both `agent_instance_id` cases — through
+  the sibling's own `DetectRunUpload`, and skips when that checkout is absent.
 
 ## Deferred
 
@@ -292,7 +297,7 @@ should be re-raised in review as a finding.
 
 | Deferred | Cost of skipping |
 |---|---|
-| `agent_instance_id` is always `null` ([#12](https://github.com/stacktrace-ai/stacktrace/issues/12)) | The wire field exists and is never populated. `Composition` has no instance field and `acquire.py` reads only `openaca:agent_kind`, so carrying it means widening both — a change to the correlation layer for a field the Cloud currently treats as optional. Worse than coarse grouping: `sync endpoint` already sends a real id read off the BOM root, and the id is part of the Cloud's agent key, so the two commands resolve to two different agent rows — inventory on one, runtime findings on the other. Fixing it later strands the null-keyed row's history. |
+| ~~`agent_instance_id` is always `null`~~ — **done**, [#12](https://github.com/stacktrace-ai/stacktrace/issues/12) | Was: the wire field existed and nothing populated it, so `sync endpoint` sent a real id off the BOM root while `sync detect` sent `null`, and the id is part of the Cloud's agent key — two agent rows for one agent, inventory on one and runtime findings on the other. Now read into `Composition.agent_instance_id` and mapped per kind in `sync_detect._instance_ids`. Note this does **not** enable several agents of one kind: `acquire` refuses two BOMs for one kind, and the map holds one id per kind. |
 | `verdict.analyzer`, `.model`, `.prompt_version` | *Which analyzer graded this, fleet-wide* is unanswerable. Cheap to add later. |
 | `Unknown.stage`, `.dispatched` | Cannot separate *the model never ran* from *the model refused*. `reason` carries most of it, but not `dispatched`, which is what keeps a session from being counted twice. |
 | Per-call timestamps | `last_invoked_at` is null on every row until `openaidr`'s `ToolCall` grows a timestamp; it carries `duration_ms`, a delta, and `Turn` carries none. |