Agent-Casuality

Causal debugging for branching multi-agent systems.

Agent-Casuality records what your agents did as a causal event graph, then explains failures with grounded evidence instead of guesses.

Why it exists

Logs and traces show what happened. When several agents branch, merge, and share state, that isn't enough to tell what actually caused a bad outcome.

Agent-Casuality adds three things ordinary observability lacks:

• Explicit causal parents for every event
• Decision contracts with baselines, so each decision has a reference point
• Counterfactual replay, which tests which inputs actually flip the outcome

Agent execution → event capture → causal graph → slice / provenance / interaction → grounded diagnosis

Install

Published as agent-casuality==0.1.3 (PyPI) and @psionic-labs/opencode-agent-casuality==0.1.3 (npm).

Requires Python 3.11+ and uv.

uv init

uv add agent-casuality
opencode plugin add @psionic-labs/opencode-agent-casuality

Try it in 30 seconds

No server, API key, or network needed:

uv run python examples/customer_approval.py

It captures two agent results and a wrong approval, then explains the failure:

Outcome: approved
Diagnosis: The terminal event is marked 'failure' because the decision returned
'approved' with customer_status='eligible' and risk_score=0.2.
Evidence:
- Minimal tested chain: customer_status + risk_score -> decision -> terminal failure
- Canonical baselines were 'ineligible' and 0.8
- Interaction between customer_status and risk_score: 1.0
Limitations: the evidence does not establish why the upstream tools produced these values.

See it: Visual DAG Explorer

Open the capture as an interactive causal graph — no API key needed. The Explorer ships inside the agent-casuality PyPI wheel (no clone needed):

# PyPI install
pip install agent-casuality
casuality-explorer

# Source checkout
uv run python -m explorer.server

Then open http://127.0.0.1:8766. The bundled demo trace loads: a failing test, the fix edit, and the passing retry, with the failure path highlighted.

Screenshot: a freshly captured shared_state_contamination run (240 events, 6 causal edges) — the checker's failure node selected, its causal chain in the inspector.

Screenshot: the bundled demo trace in the Timeline view — per-agent lanes (run, bash, edit), the retry's tool_result ("app tests pass") selected as the failure target, with the "Why did it fail?" strip and event inspector alongside.

• Graph + Timeline views of the declared causal parents — every edge was recorded at capture time, none inferred.
• Event inspector — click any node for its command, result, parents, and children.
• Analysis tabs (chain, provenance, interaction, evidence, metrics) stay informative even with no ground truth, built from capture facts.
• Your own runs: point it at a live capture — casuality-explorer --db .casuality/opencode.db (source checkout: uv run python -m explorer.server --db .casuality/opencode.db).
• Optional AI interpretation: set OPENROUTER_API_KEY (and optionally OPENROUTER_MODEL, default nvidia/nemotron-3-ultra-550b-a55b:free), then click Generate AI analysis in the "Why did it fail?" strip. The model text lives in its own labeled block — never mixed with the evidence.

Full acceptance procedure: TEST.md §29.

Use it with your agents

import casuality

casuality.init(".casuality/events.db")

@casuality.agent(role="risk_checker")
def check_risk(customer): ...

@casuality.merge_decision(...)
def approve(customer_status, risk_score): ...

See examples/customer_approval.py for a complete runnable example.

Works with OpenCode

Capture live coding-agent sessions. Telemetry is fail-open: it never interrupts your agent.

# Terminal 1: receiver (PyPI install; source checkout: uv run casuality-opencode-ingest ...)
casuality-opencode-ingest --db .casuality/opencode.db
# Terminal 2: agent (plugin posts automatically)
opencode run "Read RESEARCH.md, implement sort_items in task.py as recommended, run the test script."
# Terminal 3: Visual DAG
casuality-explorer --db .casuality/opencode.db

Full consumer flow: install agent-casuality → install the OpenCode plugin (opencode plugin add @psionic-labs/opencode-agent-casuality) → start the receiver → run OpenCode → launch casuality-explorer → inspect the recorded trace. No repository clone is needed.

Representative committed result (stale_research, OpenCode 1.19.0): completed (exit 0), 331 events, capture coverage 1.0, diagnosis scored (see benchmark/results/opencode/opencode.md). No video artifact ships with this release. Setup guide →

Benchmarks

Offline, provider-neutral suite (uv run casuality-benchmark ...) plus a real OpenCode coding-agent benchmark. Full results in docs/benchmarks.md and benchmark/results/.

• Five deterministic scenarios: 5/5 pass.
• Experiment 2 (shared-state recovery): 100/100.
• Experiment 3 (semantic-port vs raw deletion): 20/20 semantic-port successes; raw-deletion failure rate met target.
• Experiment 1 (offline): passes; external Fastino run is provider-blocked/deferred (no structured-output capability).
• Real OpenCode benchmark (5 runs / 5 tasks, OpenCode 1.19.0): capture micro/macro-average 1.0; cause recall mean 0.3 (structural-slice ancestry under explicit-evidence edges only); joint ancestry 0.0 — genuine causal interaction is unsupported from live traces.

Terminology is precise: live-trace branch results are reported as joint ancestry (not causal interaction), and minimal slices as a required-cause preservation proxy (not causal minimality).

Documentation