{"_id":"@psionic-labs/opencode-agent-causality","_rev":"4-f708ab61520e34c258bc9b703dd5c195","name":"@psionic-labs/opencode-agent-causality","dist-tags":{"latest":"0.1.6"},"versions":{"0.0.0-stage":{"name":"@psionic-labs/opencode-agent-causality","version":"0.0.0-stage","_id":"@psionic-labs/opencode-agent-causality@0.0.0-stage","stub":true,"maintainers":[{"name":"nyxied","email":"vasantmogia05@gmail.com"}],"dist":{"shasum":"0d9eaba0387e8905b9fcfce2716bc0f10c72b367","tarball":"https://registry.npmjs.org/@psionic-labs/opencode-agent-causality/-/opencode-agent-causality-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-uKS5rZusITdlzawHmCcqsoqGs7Z/s/qD+rxqZIpsptnQgRLDHepvz7jHKKmNnHfl80UTqjme+Eog3/jltD5Yrw==","signatures":[{"sig":"MEUCIHjE7ECyRT7KQdRlIumwfTmZNGSuFPwp3nDLPxh/w9bCAiEA8T4S4aUKedKTFJbkABI5c55NjFgii+92cXUAomSGS38=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":360},"_npmUser":{"name":"nyxied","email":"vasantmogia05@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.4":{"name":"@psionic-labs/opencode-agent-causality","version":"0.1.4","license":"AGPL-3.0-only","_id":"@psionic-labs/opencode-agent-causality@0.1.4","maintainers":[{"name":"nyxied","email":"vasantmogia05@gmail.com"}],"homepage":"https://github.com/Psionic-labs/Agent-Causality#readme","bugs":{"url":"https://github.com/Psionic-labs/Agent-Causality/issues"},"dist":{"shasum":"3276c223a7f318feabadf7f44d98b17bfdb5566b","tarball":"https://registry.npmjs.org/@psionic-labs/opencode-agent-causality/-/opencode-agent-causality-0.1.4.tgz","fileCount":6,"integrity":"sha512-1wky0zwT6NEmC7hIY/qBzkTt6Be2Ze+FQvXMtoHIL4SwwRtnbg9MD+nYwAVAL0qTK03rl9Y/1Bhfael3oC4RBQ==","signatures":[{"sig":"MEYCIQC/fropGIB1K5Qfxf05Y4uZ9RAzyRmI2DNQFCaxHF5uDAIhAN6/EXN7UTKL6JB2ONLzsR/dYVM88cOV4AiIXFLBUxeB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIFs+Ul1x5V4A64c6g44CjdB5G2u1Jr86RgkuU48oWbiRAiEAq09H6Z+02x04KIVlLFxgKzejWy1oFr4yCDVQ1xZfqdE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73448},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"67b42675be452d28aecde2ab2719b910fed20782","scripts":{"test":"node --test test/index.test.mjs test/telemetry.test.mjs test/loader-compat.test.mjs","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm test"},"_npmUser":{"name":"nyxied","email":"vasantmogia05@gmail.com"},"repository":{"url":"git+https://github.com/Psionic-labs/Agent-Causality.git","type":"git","directory":"packages/opencode-agent-causality"},"_npmVersion":"11.17.0","description":"OpenCode plugin that streams Agent-Causality telemetry events to the ingest endpoint","directories":{},"_nodeVersion":"26.4.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.2","@types/node":"^20.0.0","@opencode-ai/plugin":"1.18.34"},"peerDependencies":{"@opencode-ai/plugin":"1.18.34"},"_npmOperationalInternal":{"tmp":"tmp/opencode-agent-causality_0.1.4_1792436492159_0.3556554065555426","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@psionic-labs/opencode-agent-causality","version":"0.1.5","license":"AGPL-3.0-only","_id":"@psionic-labs/opencode-agent-causality@0.1.5","maintainers":[{"name":"nyxied","email":"vasantmogia05@gmail.com"}],"homepage":"https://github.com/Psionic-labs/Agent-Causality#readme","bugs":{"url":"https://github.com/Psionic-labs/Agent-Causality/issues"},"dist":{"shasum":"b0ed4e835cbf3182fa6c28695da4da5cdf7231a4","tarball":"https://registry.npmjs.org/@psionic-labs/opencode-agent-causality/-/opencode-agent-causality-0.1.5.tgz","fileCount":6,"integrity":"sha512-/GrtiM1nZI8LQzHuFO9+tzS2dsYU9bWqDZsMumIfaauTSKPLkqCg9uKubX6wQuFwr1P3Z8uwhf0lKbVh+cMoXQ==","signatures":[{"sig":"MEUCIQDFV3NINyg6QT/zIauI6GdkWboHEU/DCdxcX5pm10ffHQIgA8QT5npKAnSVwqFNtlYLKDt5kTLnsKThmhFcUqvINXA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIBsiQSTXG3uSQCRTj/vwjSBiIeIE855J6w7M7tZMlUT+AiEAvRHasdqqKEU/lVNoPZ3RSqMW34U0WSSIPZ+wwaZZmsI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@psionic-labs%2fopencode-agent-causality@0.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":72744},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"7b9f209a4d9a8c6d62cf86a76fc7702fa72d6f5b","scripts":{"test":"node --test test/index.test.mjs test/telemetry.test.mjs test/loader-compat.test.mjs","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm test"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"651fea53-d5c7-4529-9268-6ac7240bd483"}},"repository":{"url":"git+https://github.com/Psionic-labs/Agent-Causality.git","type":"git","directory":"packages/opencode-agent-causality"},"_npmVersion":"12.2.0","description":"OpenCode plugin that streams Agent-Causality telemetry events to the ingest endpoint","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.2","@types/node":"^20.0.0","@opencode-ai/plugin":"1.18.34"},"peerDependencies":{"@opencode-ai/plugin":"1.18.34"},"_npmOperationalInternal":{"tmp":"tmp/opencode-agent-causality_0.1.5_1792437192418_0.7760859909780438","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"_id":"@psionic-labs/opencode-agent-causality@0.1.6","bugs":{"url":"https://github.com/Psionic-labs/Agent-Causality/issues"},"dist":{"shasum":"f3eec77d75e86360fdd85c6b42e729a6828a135e","tarball":"https://registry.npmjs.org/@psionic-labs/opencode-agent-causality/-/opencode-agent-causality-0.1.6.tgz","fileCount":6,"integrity":"sha512-sSNmbA2kDwaCVLYRVeSXHEGRfeCQnJZVhPbDU+kYvR/pQXEwN5FOFnvjYpxcMl2T3r4PYbjHf/1Jcv3P/PfOWQ==","signatures":[{"sig":"MEYCIQDO4JO2K6+na+VF1eLJpRhQV46/dtADHOTFM5TAlFZZcAIhAKhWuE+pVXqsX3gD3DHfkgxXW8xh8BuXs4EQtZie2kPu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICvuQUHdodIB5btcccXZK1I6q6ioKYwUHA+SIBH3YBXLAiEA7nPibQUL2hpQyl3vEbq4rUp+9JFCXGkHIcKHMau4to8="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@psionic-labs%2fopencode-agent-causality@0.1.6","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":73408},"main":"./dist/index.js","name":"@psionic-labs/opencode-agent-causality","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"d060894638307d9429b8458328563be86eb24205","license":"AGPL-3.0-only","scripts":{"test":"node --test test/index.test.mjs test/telemetry.test.mjs test/loader-compat.test.mjs","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm test"},"version":"0.1.6","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"651fea53-d5c7-4529-9268-6ac7240bd483"}},"homepage":"https://github.com/Psionic-labs/Agent-Causality#readme","repository":{"url":"git+https://github.com/Psionic-labs/Agent-Causality.git","type":"git","directory":"packages/opencode-agent-causality"},"_npmVersion":"12.2.1","description":"OpenCode plugin that streams Agent-Causality telemetry events to the ingest endpoint","directories":{},"maintainers":[{"name":"nyxied","email":"vasantmogia05@gmail.com"}],"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.2","@types/node":"^20.0.0","@opencode-ai/plugin":"1.18.34"},"peerDependencies":{"@opencode-ai/plugin":"1.18.34"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-agent-causality_0.1.6_1792688253878_0.35973707064203175"}}},"time":{"created":"2026-10-19T19:00:14.057Z","modified":"2026-10-22T16:57:34.405Z","0.0.0-stage":"2026-10-19T19:00:14.057Z","0.1.4":"2026-10-19T19:01:32.318Z","0.1.5":"2026-10-19T19:13:12.505Z","0.1.6":"2026-10-22T16:57:34.013Z"},"bugs":{"url":"https://github.com/Psionic-labs/Agent-Causality/issues"},"license":"AGPL-3.0-only","homepage":"https://github.com/Psionic-labs/Agent-Causality#readme","repository":{"url":"git+https://github.com/Psionic-labs/Agent-Causality.git","type":"git","directory":"packages/opencode-agent-causality"},"description":"OpenCode plugin that streams Agent-Causality telemetry events to the ingest endpoint","maintainers":[{"name":"nyxied","email":"vasantmogia05@gmail.com"}],"readme":"# Agent-Causality\n\n[![PyPI version](https://img.shields.io/pypi/v/agent-causality)](https://pypi.org/project/agent-causality/)\n[![npm version](https://img.shields.io/npm/v/@psionic-labs/opencode-agent-causality)](https://www.npmjs.com/package/@psionic-labs/opencode-agent-causality)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-green)](https://github.com/Psionic-labs/Agent-Causality/blob/main/LICENSE)\n[![OpenCode 1.19+](https://img.shields.io/badge/opencode-1.19%2B-purple)](https://opencode.ai)\n\n*Causal debugging for branching multi-agent systems — plus capture adapters for OpenCode and LangGraph.*\n\nAgent-Causality records what your agents did as a causal event graph, then\nexplains failures with grounded evidence instead of guesses.\n\n> **This README is identical on both registries.** The full system needs\n> **both** packages:\n>\n> - **Python (`agent-causality` on PyPI)** — SDK, CLI, ingest receiver\n>   (`causality-opencode-ingest`), and Visual DAG Explorer\n>   (`causality-explorer`). Installing only this gives you the offline demo\n>   but no live OpenCode capture.\n> - **JavaScript (`@psionic-labs/opencode-agent-causality` on npm)** —\n>   OpenCode plugin (telemetry capture only). Installing only this gives you\n>   events with nowhere to persist or view them.\n>\n> Source: <https://github.com/Psionic-labs/Agent-Causality>\n\n[Demo video](#demo-video) ·\n[Install](#install--you-need-both-packages) ·\n[30-second demo](#try-it-in-30-seconds-no-server-key-or-network) ·\n[Single-run capture](#single-run-capture-ingest--opencode--explorer) ·\n[Explorer](#see-it-visual-dag-explorer) ·\n[OpenCode](#works-with-opencode) ·\n[LangGraph](#works-with-langgraph) ·\n[Docs](#documentation)\n\n---\n\n## Demo video\n\n[![Agent-Causality demo — watch on YouTube](https://img.youtube.com/vi/bogmzYe9Hzs/maxresdefault.jpg)](https://www.youtube.com/watch?v=bogmzYe9Hzs)\n\n*Full walkthrough, click the thumbnail to watch on YouTube.*\n\n*The Video follows the Single-run capture given below*\n\n---\n\n## Why it exists\n\nLogs and traces show *what happened*. When several agents branch, merge, and\nshare state, that isn't enough to tell *what actually caused* a bad outcome.\n\nAgent-Causality adds three things ordinary observability lacks:\n\n| Gap in ordinary observability | What Agent-Causality records |\n| --- | --- |\n| Scattered logs, no links | **Explicit causal parents** for every event |\n| Decisions with no reference point | **Decision contracts with baselines** |\n| Guesses about \"what if\" | **Counterfactual replay** that tests which inputs flip the outcome |\n\n```text\nAgent execution → event capture → causal graph → slice / provenance / interaction → grounded diagnosis\n```\n\n---\n\n## Install — you need BOTH packages\n\nPublished as `agent-causality==0.2.1`\n([PyPI](https://pypi.org/project/agent-causality/)) and\n`@psionic-labs/opencode-agent-causality==0.1.6`\n([npm](https://www.npmjs.com/package/@psionic-labs/opencode-agent-causality)).\nRequires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/)\nfor source checkouts; PyPI/npm consumers only need `pip`/`opencode`.\n\n```bash\n# 1. Python side (SDK + receiver + explorer + CLI)\npip install agent-causality\n# or, inside a uv project:\nuv add agent-causality\n\n# 2. JavaScript side (OpenCode capture plugin — telemetry only)\nopencode plugin add @psionic-labs/opencode-agent-causality\n```\n\n> **npm-only installers:** you still need the PyPI package — the Visual DAG\n> Explorer and the `causality-opencode-ingest` receiver ship **only** in\n> `agent-causality`, not in this npm package.\n>\n> **PyPI-only installers:** you still need the npm package for live OpenCode\n> capture — `pip install agent-causality` alone cannot observe an OpenCode\n> session without the plugin.\n\n*Optional — AI explanation extra.* Only needed for LLM-grounded `explain` /\n*Generate AI analysis* (needs `httpx` + `OPENROUTER_API_KEY`):\n\n```bash\n# pip consumer\npip install \"agent-causality[explain]\"\n# uv project\nuv add \"agent-causality[explain]\"\n# source checkout\nuv sync --extra explain\n```\n\n---\n\n## Try it in 30 seconds (no server, key, or network)\n\n```bash\nuv run python examples/customer_approval.py\n```\n\nIt captures two agent results and a wrong approval, then explains the failure:\n\n```text\nOutcome: approved\nDiagnosis: The terminal event is marked 'failure' because the decision returned\n'approved' with customer_status='eligible' and risk_score=0.2.\nEvidence:\n- Minimal tested chain: customer_status + risk_score -> decision -> terminal failure\n- Canonical baselines were 'ineligible' and 0.8\n- Interaction between customer_status and risk_score: 1.0\nLimitations: the evidence does not establish why the upstream tools produced these values.\n```\n\n---\n\n## Single-run capture: ingest → opencode → explorer\n\nThe minimal end-to-end loop. One isolated SQLite file per run keeps traces\nseparate (`.causality/single-run.db` below is just an example — any path\nworks) and port `8797` avoids clashing with the default `8766` explorer.\n\n**Terminal 1 — start the receiver:**\n\n```bash\n# PyPI install\ncausality-opencode-ingest --db .causality/single-run.db\n# Source checkout\nuv run causality-opencode-ingest --db .causality/single-run.db\n```\n\n**Terminal 2 — run one instrumented agent task** (plugin posts automatically):\n\n```bash\nopencode run \"Run the existing tests before editing. Diagnose and fix the bug in discount.py so both tests pass. Do not modify the tests. Rerun the tests and summarize the change.\"\n```\n\n*Optional — enable AI explanations for this project:*\n\n```bash\nuv add \"agent-causality[explain]\"\n# pip equivalent: pip install \"agent-causality[explain]\"\n```\n\n**Terminal 3 — inspect the trace in the Visual DAG Explorer:**\n\n```bash\n# PyPI install\ncausality-explorer --db .causality/single-run.db --port 8797\n# Source checkout\nuv run python -m explorer.server --db .causality/single-run.db --port 8797\n```\n\nThen open <http://127.0.0.1:8797>. Each `opencode run` appends to the same\n`--db` file; use a fresh `--db` path per task for one-trace-per-file\n(any filename works).\n\n---\n\n## See it: Visual DAG Explorer\n\nOpen any capture as an interactive causal graph — no API key needed.\nThe Explorer ships inside the `agent-causality` PyPI wheel (no clone needed):\n\n```bash\n# PyPI install\npip install agent-causality\ncausality-explorer\ncausality-explorer --db .causality/opencode.db --port 8766\n```\n\n```bash\n# Source checkout\nuv run python -m explorer.server\nuv run python -m explorer.server --db .causality/opencode.db --port 8766\n# Single-run variant from the section above:\nuv run python -m explorer.server --db .causality/single-run.db --port 8797\n```\n\nThen open <http://127.0.0.1:8766> (or `:8797` for the single-run variant).\nThe bundled demo trace loads: a failing test, the fix edit, and the passing\nretry, with the failure path highlighted.\n\n![Animated tour of the Visual DAG Explorer — graph, timeline, and metrics views](https://github.com/Psionic-labs/Agent-Causality/raw/main/docs/media/explorer-demo.gif)\n\n*Short tour of the bundled demo trace: select the failing `tool_result`,\nswitch to the Timeline view, open the Metrics census, then return to the\ngraph. Also available as [MP4](https://github.com/Psionic-labs/Agent-Causality/raw/main/docs/media/explorer-demo.mp4).*\n\n![Visual DAG Explorer — live OpenCode trace with the failure target selected, causal edges, and inspector](https://github.com/Psionic-labs/Agent-Causality/raw/main/docs/screenshots/explorer-shared-state-fresh.png)\n\n*Freshly captured `shared_state_contamination` run (240 events, 6 causal\nedges) — the checker's failing `tool_result` selected. The header reads\n**Fallback target** because the diagnosis target came from the last-event\nfallback; its command and result are in the inspector.*\n\n![Visual DAG Explorer Timeline view — per-agent lanes in sequence order, the failure target selected, with minimap and event inspector](https://github.com/Psionic-labs/Agent-Causality/raw/main/docs/screenshots/timeline.png)\n\n*Bundled demo trace in the Timeline view — per-agent lanes (run, bash, edit),\nthe retry's `tool_result` (\"app tests pass\") selected as the failure target,\nwith the \"Why did it fail?\" strip and event inspector alongside. The chrome\nis cosmetic; the top strip reads **Read-only** because the explorer never\nwrites to a capture.*\n\nWhat you get:\n\n- **Graph + Timeline views** of the declared causal parents — every edge\n  was recorded at capture time, none inferred.\n- **Event inspector** — click any node for its command, result, parents,\n  and children.\n- **Analysis tabs** (chain, provenance, interaction, evidence, metrics)\n  stay informative even with no ground truth, built from capture facts.\n- **Your own runs**: point it at a live capture —\n  `causality-explorer --db .causality/opencode.db`\n  (source checkout: `uv run python -m explorer.server --db .causality/opencode.db`).\n- **Optional AI interpretation**: install the `explain` extra\n  (`pip install \"agent-causality[explain]\"` / `uv add \"agent-causality[explain]\"`),\n  set `OPENROUTER_API_KEY` (and optionally `OPENROUTER_MODEL`, default\n  `nvidia/nemotron-3-ultra-550b-a55b:free`), then click *Generate AI analysis*\n  in the \"Why did it fail?\" strip. The model text lives in its own labeled\n  block — never mixed with the evidence.\n\nFull acceptance procedure:\n[TEST.md §29](https://github.com/Psionic-labs/Agent-Causality/blob/main/TEST.md).\n\n---\n\n## Use it with your agents\n\n```python\nimport causality\n\ncausality.init(\".causality/events.db\")\n\n@causality.agent(role=\"risk_checker\")\ndef check_risk(customer): ...\n\n@causality.merge_decision(...)\ndef approve(customer_status, risk_score): ...\n```\n\nSee\n[`examples/customer_approval.py`](https://github.com/Psionic-labs/Agent-Causality/blob/main/examples/customer_approval.py)\nfor a complete runnable example.\n\n---\n\n## Works with OpenCode\n\nCapture live coding-agent sessions. Telemetry is fail-open: it never\ninterrupts your agent. **Requires both packages** (receiver from PyPI,\nplugin from npm).\n\n```bash\n# Terminal 1: receiver (PyPI install; source checkout: uv run causality-opencode-ingest ...)\ncausality-opencode-ingest --db .causality/opencode.db\n# Terminal 2: agent (plugin posts automatically)\nopencode run \"Read RESEARCH.md, implement sort_items in task.py as recommended, run the test script.\"\n# Terminal 3: Visual DAG\ncausality-explorer --db .causality/opencode.db\n```\n\nFull consumer flow: install `agent-causality` (PyPI) → install the OpenCode\nplugin (`opencode plugin add @psionic-labs/opencode-agent-causality`, npm) →\nstart the receiver → run OpenCode → launch `causality-explorer` → inspect the\nrecorded trace. No repository clone is needed.\n\n> Representative committed result (`stale_research`, OpenCode `1.19.0`):\n> `completed (exit 0), 331 events, capture coverage 1.0, diagnosis scored`\n> (see `benchmark/results/opencode/opencode.md`). No video artifact ships\n> with this release.\n> [Setup guide →](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/opencode.md)\n\n### What the plugin captures\n\nThe npm plugin forwards OpenCode's global event stream plus explicit hooks\n(`tool.execute.before/after`, `permission.ask`, `command.execute.before`,\n`chat.message`, `chat.params`). The Python receiver maps these onto canonical\nevents, registers file writes with Resource-Version machinery, and redacts\nsecrets before SQLite persistence. It is telemetry capture only — the\nExplorer and CLI live in the PyPI distribution.\n\n---\n\n## Works with LangGraph\n\n`CausalityCallbackHandler` is a LangChain callback handler: point your\ngraph's `config` at it and every node, tool, and LLM run lands in the\ncausal graph — fail-open, with `parent_run_id` containment converted into\nexplicit causal edges (unknown parents are dropped, never invented).\n\n```python\nfrom adapters.langgraph import CausalityCallbackHandler\nfrom storage.sqlite import SQLiteEventStore\n\nstore = SQLiteEventStore(\".causality/langgraph.db\")\nhandler = CausalityCallbackHandler(store)\n\napp.invoke(inputs, config=handler.config())\n```\n\nWorked example: a deterministic replay of the documented July 2025 Replit\nincident — freeze violated, production rows deleted, fabricated data\nwritten, false rollback claim — captured as 22 causally-validated events\nin\n[`examples/replit_incident.py`](https://github.com/Psionic-labs/Agent-Causality/blob/main/examples/replit_incident.py)\n(write-up:\n[docs/case-study-replit.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/case-study-replit.md)).\n[Adapter guide →](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/langgraph.md)\n\n---\n\n## Benchmarks\n\nOffline, provider-neutral suite (`uv run causality-benchmark ...`) plus a\nreal OpenCode coding-agent benchmark. Full results in\n[`docs/benchmarks.md`](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/benchmarks.md)\nand `benchmark/results/`.\n\n- Five deterministic scenarios: **5/5 pass**.\n- Experiment 2 (shared-state recovery): **100/100**.\n- Experiment 3 (semantic-port vs raw deletion): **20/20** semantic-port\n  successes; raw-deletion failure rate met target.\n- Experiment 1 (offline): passes; external Fastino run is\n  provider-blocked/deferred (no structured-output capability).\n- Real OpenCode benchmark (5 runs / 5 tasks, OpenCode `1.19.0`): capture\n  micro/macro-average `1.0`; cause recall mean `0.3` (structural-slice\n  ancestry under explicit-evidence edges only); joint ancestry `0.0` —\n  genuine causal interaction is unsupported from live traces.\n\n*Terminology is precise: live-trace branch results are reported as\n`joint ancestry` (not causal interaction), and minimal slices as a\n`required-cause preservation proxy` (not causal minimality).*\n\n---\n\n## Documentation\n\n| Topic | Link |\n| --- | --- |\n| Getting started | [GETTING_STARTED.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/GETTING_STARTED.md) |\n| OpenCode integration | [docs/opencode.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/opencode.md) |\n| LangGraph integration | [docs/langgraph.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/langgraph.md) |\n| Replit incident case study | [docs/case-study-replit.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/case-study-replit.md) |\n| CLI and Python reference | [docs/reference.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/reference.md) |\n| Benchmarks and results | [docs/benchmarks.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/benchmarks.md) |\n| Scope and limits | [docs/reference.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/reference.md) |\n| Research background | [docs/thesis.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/thesis.md), [docs/research-memo.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/docs/research-memo.md) |\n| Contributing and tests | [TEST.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/TEST.md), [CONTRIBUTING.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/CONTRIBUTING.md) |\n| Release notes | [CHANGELOG.md](https://github.com/Psionic-labs/Agent-Causality/blob/main/CHANGELOG.md) |\n","readmeFilename":"README.md"}