Agent-Causality 0.3.0

Agent-Causality 0.3.0

Breaking changes

• capture_tool now requires provenance_recorder when field_sources produces a
  non-empty mapping. Callable recorders must return an EventLog, and captured
  tool retries without provenance are rejected.

Failure story on the causal DAG

• The failure column shows the failure's visible declared ancestors. Hidden
  stretches become dashed filter gaps or stubs with the omitted event count,
  and selecting a node lights only its causal ancestors, stopping at a gap.
• Gap tooltips report the hidden count, including when the same visible pair
  also has a direct causal edge.
• Zoom and pan respect the SVG letterbox at every viewport aspect ratio.
• The explorer opens the session that owns the failure event by default.

Capture, CLI, and explorer boundaries

• Invalid replay values fail with usage guidance instead of silently becoming
  a string.
• EventLog.append must return the stored Event or raise; fail-open logs use the
  new AppendWithStatus protocol.
• The explorer serves only the vendored explorer/static bundle.
• .env loading moved to sdk/env.py, with inline comment stripping and startup
  errors for unreadable files.
• Diagnosis scoring moved into core/diagnosis.py and core/metrics.py.

Examples, site, and docs

• Added the payment approval failure example.
• Redesigned the site as a causal-graph landing page, with OpenCode and
  LangGraph guides and a mobile menu.
• Published the research paper with Google Scholar metadata and added live
  PyPI and npm download badges.

Verification and agent tooling

• Added deterministic quick and full verify modes with ephemeral ports and
  artifact logs, wired into pre-commit, CI, and agent worktrees.
• Added import-boundary, suppression-budget, static-freshness, plugin-copy,
  and linked-worktree checks.
• Added the worktree spawner, worktree cleanup command, task-scope enforcement,
  and advisory pull request review.

Install
pip install agent-causality==0.3.0
npm install @psionic-labs/opencode-agent-causality@0.1.7

OpenCode plugin 0.1.7

OpenCode plugin 0.1.7

• Republish the README with the website, research paper, guide, and download
  badge links.
• Runtime behavior is unchanged from 0.1.6.

Install
npm install @psionic-labs/opencode-agent-causality@0.1.7

v0.2.1 - CRT explorer and refreshed media

CRT monitor visual system for the Visual DAG Explorer.

• Beige chassis with red control strips, a crimson CRT screen, vignette/glare, and a Read-only indicator.
• IBM Plex Mono 400/500/600 bundled locally; no external font requests.
• Square DAG markers, amber selection, and a warm CRT timeline palette. Events, status language, and the read-only contract are unchanged.
• Refreshed stills plus a demo GIF/MP4, produced by the new zero-dependency Edge/CDP capture script.

Python package: agent-causality 0.2.1.

The OpenCode plugin README refresh ships independently as 0.1.6 from tag plugin-v0.1.6; plugin runtime code is unchanged.

v0.2.0 - Capture adapters + LangGraph integration

Highlights

• LangGraph capture adapter — CasualityCallbackHandler records chain/tool/LLM/retriever callbacks as causal events: one root run = one agent, unknown causal parents are dropped (no invented edges), frontier chaining orders siblings, and file read-after-write edges link readers to their last writer. Fail-open by design (handler.errors, never raises into your agent). Install with agent-casuality[langgraph].
• Capture adapters package — OpenCode capture moved from opencode_adapter/ to adapters/opencode/ (git history preserved; the casuality-opencode-ingest entry point is unchanged). Breaking (pre-1.0): direct imports of opencode_adapter must move to adapters.opencode.
• Replit incident case study — deterministic replay of the documented July 2025 Replit incident (examples/replit_incident.py, no API key): the destructive delete sits in the freeze's causal slice with zero approval events, the fabricated write is a direct causal parent of the "verification" read, and the false rollback claim lands two events after it. Write-up: docs/case-study-replit.md.
• Visual DAG Explorer — node labels now fall back to callback names, so LangGraph captures render tool_call · write_sql instead of repeating the event type; failure/diagnosis/evidence endpoints all work on LangGraph traces.

Also in this release

• Shared deep-redaction helper for adapters; sensitive-key regex tightened (token_usage no longer redacted, access_token-style keys still are).
• Deterministic, idempotent event IDs and JSON-safe payload truncation (4000 chars).
• Root .opencode/ is git-ignored — it's an installed copy of the canonical plugin at packages/opencode-agent-casuality/src/index.ts; the plugin-compat script installs it automatically.
• Docs: new docs/langgraph.md; README (PyPI + npm copies) re-synced.

Full changelog: https://github.com/Psionic-labs/Agent-Casuality/blob/main/CHANGELOG.md

Install: pip install agent-casuality==0.2.0 or uv add agent-casuality

v0.1.4

Full Changelog: v0.1.3...v0.1.4

v0.1.3

Visual DAG explorer now ships inside the PyPI wheel

Previously, pip install agent-casuality gave you only explorer/*.py + demo JSONs — opening the explorer 404'd on / because the compiled frontend (frontend/out/) was gitignored and never packaged. 0.1.3 fixes that: the wheel and sdist now bundle the full Visual DAG frontend.

What's included

• Vendored frontend bundle — explorer/static/ (20 files: index.html + _next/ JS/CSS), synced from frontend/out/ via scripts/sync-explorer-static.py (CI-enforced with --check, so the bundle can never silently go stale).
• CWD-independent asset resolution — explorer.server.get_frontend_dir() serves the bundle from inside the installed package; no reliance on checkout layout (dev fallback to frontend/out/ kept).
• New casuality-explorer entry point (explorer.server:main), alongside the existing casuality-opencode-ingest receiver.
• Packaging regression tests — tests/test_packaging.py fails if the bundle, asset references, entry points, or path resolution regress.
• OpenCode plugin telemetry — batched delivery (up to CASUALITY_OPENCODE_BATCH_MAX, default 25), quiet fail-open by default, per-request endpoint/timeout/batch config.

Try it with no repo clone

uvpip install agent-casuality
casuality-opencode-ingest --db .casuality/opencode.db   # start receiver
# run OpenCode with the plugin, generate a trace, then:
casuality-explorer --db .casuality/opencode.db          # open the Visual DAG

plugin-v0.1.3

What's in 0.1.3 (from CHANGELOG.md)

Also on npm as @psionic-labs/opencode-agent-casuality@0.1.3:

npm i @psionic-labs/opencode-agent-casuality@0.1.3

OpenCode plugin telemetry

• Batched delivery: envelopes drain in batches of up to
  CASUALITY_OPENCODE_BATCH_MAX (default 25) per POST; singletons stay
  single objects. Short persisted/accepted counts retry the batch;
  count-less 2xx bodies still count as delivered.
• Quiet fail-open by default: delivery warnings emit only when
  CASUALITY_OPENCODE_LOG_TELEMETRY_FAILURES=1/true, rate-limited, with
  the first warning naming the endpoint and receiver start command.
• Per-request config: endpoint, bearer token, timeout
  (CASUALITY_OPENCODE_INGEST_TIMEOUT_MS, default 5000), and batch size
  resolve per request; retry backoff is 200ms/400ms.
• CI frontend job now uses Node.js 24.

Docs: refreshed to match current behavior

• All user-facing docs synced to the working tree: GETTING_STARTED
  (OpenCode 1.19.0, explorer coverage, current AI model default),
  docs/reference.md (explorer/ingest endpoints, plugin env table,
  benchmark commands), docs/opencode.md and the npm README (quiet
  fail-open default, batching/backoff, full env table),
  docs/benchmarks.md and benchmark/README.md (retired-model notes),
  README (AI default), CONTRIBUTING (frontend gates), PROOF.md,
  LEGACY_README.md, and frontend/DESIGN.md (current suite counts).

Docs: TEST.md slimmed, verification archive

• TEST.md shrank from ~1100 to ~340 lines: it now covers the quick
  gates, benchmark verification, a fixture CLI smoke block, a
  focused-test-files table, short PostgreSQL notes, and the current
  Phase 5/6, OpenCode (§28), and explorer (§29) procedures. Section
  numbers 28/29 are unchanged, so existing links still resolve.
• The historical Phase 2-4 PostgreSQL/SQL checks (§§1-24) moved
  verbatim to docs/verification-archive.md with a status banner;
  GETTING_STARTED.md now links there for schema/query detail.

Landed on main just after this tag (not in 0.1.3)

• .github/workflows: actions/checkout v4 → v7, actions/setup-node
  v4 → v7, astral-sh/setup-uv v5 → v6 (CI green; the Node-20 warning
  for setup-uv persists until upstream migrates its runtime).

v0.1.2

AI diagnosis fixes

• Default model is now nvidia/nemotron-3-ultra-550b-a55b:free (deepseek/deepseek-v4-flash:free was retired from OpenRouter's free tier and broke Generate AI analysis with a 502). Override with OPENROUTER_MODEL.
• /api/ai-diagnosis no longer leaks model failures as HTTP 500: missing httpx → 503, other model errors → 502 with the cause attached. The frontend now shows the backend's error detail.

Timeline polish

• Graph and Timeline share one view budget; gaps scale with zoom; slimmer lanes; fitScale fills short traces.

Automation

• New Trusted Publishing workflow: creating a v* release runs tests, builds, and publishes to PyPI automatically.

For more details: check recent commits

plugin-v0.1.1

• OpenCode 1.19 loader compatibility
• Honest telemetry causality and receiver ack semantics
• README scope note: telemetry capture only; the Visual DAG Explorer ships with the `agent-casuality Python distribution

v0.1.0

First public release (PyPI: agent-casuality==0.1.0).

• Causal event capture/graph, merge-local counterfactual replay, structural/minimal-slice analysis, exact provenance, Shapley interaction.
• Offline benchmark suite: 5/5 deterministic scenarios, Experiment 2 100/100, Experiment 3 semantic-port 20/20 (raw-deletion 0.7 vs >0.35 target), failure-injection 3/3.
• agent-replay 0.2.0 baseline (divergence localization only; causal capabilities unsupported).
• Fail-open OpenCode adapter + local ingest receiver and real OpenCode coding-agent benchmark (capture micro 0.928 / macro 0.967).
• External Fastino Experiment 1 provider-blocked/deferred (no structured-output capability); offline Experiment 1 passes.

See CHANGELOG.md for details.