Moved to probityai/probity/packages/observer. Star and follow it there. This repository is archived; its tags and releases keep working.
Record brokered agent writes and check selected native framework reports offline.
Use it in agent harnesses and evaluation pipelines that need replayable action records or a consumer gate for retained reports.
Install the root package: pip install agent-evidence-observer==0.0.2.
Run the demo from the released package. You need Python 3.12 or later and uv; there is nothing to clone.
uvx agent-evidence-observer==0.0.2 demo ./sample-run
uvx agent-evidence-observer==0.0.2 verify ./sample-runThe two commands print:
{"noDetectedGap": "true", "retryReplayed": "true", "status": "verified", "witnessScope": "PEER"}
{"noDetectedGap": "true", "status": "verified", "witnessScope": "PEER"}
sample-run/ now holds the signed packet, the history, the public keys and the file tree. The demo
writes a file, retries it, and the retry returns the first effect. noDetectedGap means the broker's
file-tree snapshots found no change it did not make. It does not mean every agent effect was seen.
To run from a pinned source checkout instead, see Run the source quick start.
The root distribution is version 0.0.2. Every record says witnessScope: PEER: the witness key runs on the same
host under the same operator, so the records show what this broker saw, not what an independent
observer saw. Linux runs can launch a fixed probe, or a Python script given to run-workload, under
bubblewrap with only the broker's socket exposed. launch-agent runs an unmodified agent in docker or
apptainer and records, from outside it, every program it ran and every file it changed. It does not use
bubblewrap, which cannot start on hosts with apparmor_restrict_unprivileged_userns=1 such as Ubuntu 24.04.
agent-evidence-witness runs a separately operated witness: a record it co-signs verifies as EXTERNAL
when the reader pins a different operator for the witness key. It needs the witness extra, which is not yet
in a released wheel.
Start with worked examples to follow a practical question, then open its technical reference for commands and exact evidence.
| page | read it for |
|---|---|
| Start a project | a template that records a write with this package and checks it with probity-verify, pinned and in CI |
| Component tour | every part of the prototype in one paragraph each, with links: ticket service, replay, evaluation history, A2A, AAE, protected dispatch |
| Running the demo | the full install with tests, and what each output field means |
| Design, trust boundary and roadmap | what each mechanism checks and does not establish, the Linux boundary gate, recovery, consumer admission, and the roadmap |
| Agent launcher | run an unmodified agent with three outside sensors and check its claims with probity-verify |
| Isolated producer | the acceptance criteria for running an unmodified agent behind the broker |
| Brokered workload | run a Python script behind the write broker with run-workload, then check it offline with verify-workload |
| Witness ledger | signed begin and terminal receipts, and how a reader checks them |
| Separately operated witness | run a witness on another host, co-sign records 2-of-2, and catch a witness that forks its log |
| Installation and profile selection | choose the root wheel, a separate profile wheel or a selected source reader; runtime requirements and installed examples |
| Release the root package | qualify a wheel and source distribution, then publish with a bound source tag |
| Atomic native reader | install an offline reader for selected native delegation runs and their refusal controls |
| Witnessed run selection | check a selected run against consumer-retained opening and closing checkpoints |
| Approved refund retries | run the APS approval and local SQLite example, then check retries and refusals with a separately installed reader |
| Refund handoff conformance | verify admission, recovery, handoff, effect and reconciliation bindings against 80 public vectors |
Apache License 2.0; see LICENSE.