agenticreplay 0.1.0 → 0.1.2

package/python/tests/test_reader.py

@@ -1,423 +0,0 @@
-"""TraceReader: the tolerances spec §2 mandates, and the reporting that keeps them honest."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import tracemalloc
-from pathlib import Path
-
-import pytest
-from conftest import blob_of, event, write_trace
-
-from agenticreplay_trace import BlobRef, TraceEvent, TraceFormatError
-from agenticreplay_trace.reader import BlobIntegrityError, BlobNotFoundError, NotATraceError, TraceReader
-
-
-def files_in(directory: Path) -> dict[str, tuple[int, bytes]]:
-    """Every file's mtime and content — the fixture for proving nothing was written."""
-    out = {}
-    for path in sorted(directory.rglob("*")):
-        if path.is_file():
-            out[str(path.relative_to(directory))] = (path.stat().st_mtime_ns, path.read_bytes())
-    return out
-
-
-class TestOpen:
-    def test_opens_a_run_directory_and_parses_its_manifest(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, "run.start")], manifest={"run_id": "run_9f2c14a03b71"})
-        reader = TraceReader.open(tmp_path)
-        assert reader.manifest.run_id == "run_9f2c14a03b71"
-        assert reader.manifest.adapter_id == "test-adapter"
-        assert reader.run_dir == tmp_path
-
-    def test_accepts_a_string_path(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, "run.start")])
-        assert TraceReader.open(str(tmp_path)).manifest.schema_version == "0.4.0"
-
-    def test_refuses_a_directory_with_no_manifest(self, tmp_path: Path) -> None:
-        with pytest.raises(NotATraceError, match="manifest.json"):
-            TraceReader.open(tmp_path)
-
-    def test_refuses_a_manifest_that_is_not_json(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [])
-        (tmp_path / "manifest.json").write_text("{not json", encoding="utf-8")
-        with pytest.raises(NotATraceError, match="not JSON"):
-            TraceReader.open(tmp_path)
-
-    def test_refuses_a_manifest_that_violates_the_schema(self, tmp_path: Path) -> None:
-        """A manifest is opened once and trusted afterwards, so it is validated, not tolerated."""
-        write_trace(tmp_path, [], manifest={"run_id": "nope"})
-        with pytest.raises(TraceFormatError, match="run_id"):
-            TraceReader.open(tmp_path)
-
-
-class TestEvents:
-    def test_reads_every_event_in_order(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(i) for i in range(5)])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1, 2, 3, 4]
-        assert all(isinstance(e, TraceEvent) for e in reader.events())
-        assert reader.problems() == []
-
-    def test_stream_yields_the_same_events_as_events(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(i) for i in range(5)])
-        reader = TraceReader.open(tmp_path)
-        assert list(reader.stream()) == reader.events()
-
-    def test_stream_does_not_load_the_file_into_memory(self, tmp_path: Path) -> None:
-        """A trace can be hundreds of MB; taking the first event must not cost the whole file."""
-        write_trace(tmp_path, [event(i, attrs={"pad": "x" * 500}) for i in range(4000)])
-        size = (tmp_path / "events.jsonl").stat().st_size
-        assert size > 2_000_000, "fixture too small to prove anything"
-        reader = TraceReader.open(tmp_path)
-
-        tracemalloc.start()
-        try:
-            stream = reader.stream()
-            first = next(stream)
-            _, peak = tracemalloc.get_traced_memory()
-        finally:
-            tracemalloc.stop()
-        stream.close()
-
-        assert first.seq == 0
-        assert peak < size // 8, f"peak {peak} for a {size} byte trace — the file was buffered"
-
-    def test_ignores_blank_lines(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1)])
-        path = tmp_path / "events.jsonl"
-        path.write_text(path.read_text(encoding="utf-8").replace("\n", "\n\n"), encoding="utf-8")
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1]
-        assert reader.problems() == []
-
-    def test_tolerates_windows_line_endings(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1)])
-        path = tmp_path / "events.jsonl"
-        path.write_bytes(path.read_bytes().replace(b"\n", b"\r\n"))
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1]
-
-    def test_reports_a_missing_events_file_without_raising(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0)])
-        (tmp_path / "events.jsonl").unlink()
-        reader = TraceReader.open(tmp_path)
-        assert reader.events() == []
-        assert any("events.jsonl" in p and "missing" in p for p in reader.problems())
-
-
-class TestTruncatedFinalLine:
-    """Spec §2: readers MUST tolerate a truncated final line — a crash during write."""
-
-    def test_skips_it_reports_it_and_does_not_raise(self, tmp_path: Path) -> None:
-        write_trace(
-            tmp_path,
-            [event(0, "run.start"), event(1)],
-            trailing='{"seq":2,"ts":"2026-08-29T10:00:00.000Z","mono_us":2000,"tur',
-        )
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1]
-        problems = reader.problems()
-        assert len(problems) == 1
-        assert "truncated final line" in problems[0]
-        assert "line 3" in problems[0]
-
-    def test_a_run_that_crashed_before_run_end_is_still_readable(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, "run.start")], trailing="{", seal=False)
-        reader = TraceReader.open(tmp_path)
-        assert [e.type for e in reader.events()] == ["run.start"]
-
-    def test_a_complete_final_line_without_a_newline_is_not_a_casualty(self, tmp_path: Path) -> None:
-        """Tolerating truncation must not mean distrusting the last line."""
-        write_trace(tmp_path, [event(0), event(1)])
-        path = tmp_path / "events.jsonl"
-        path.write_text(path.read_text(encoding="utf-8").rstrip("\n"), encoding="utf-8")
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1]
-        assert reader.problems() == []
-
-    def test_an_unknown_type_on_the_final_line_is_reported_as_unknown_not_truncated(
-        self, tmp_path: Path
-    ) -> None:
-        write_trace(tmp_path, [event(0), event(1, "gpu.allocate")])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0]
-        assert any("gpu.allocate" in p for p in reader.problems())
-        assert not any("truncated" in p for p in reader.problems())
-
-    def test_a_malformed_line_that_is_not_last_is_reported_as_malformed(self, tmp_path: Path) -> None:
-        """Only the final line gets the benefit of the doubt; an earlier one is corruption."""
-        write_trace(tmp_path, [event(0), event(1), event(2)])
-        path = tmp_path / "events.jsonl"
-        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
-        lines[1] = "{oh no\n"
-        path.write_text("".join(lines), encoding="utf-8")
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 2]
-        problems = reader.problems()
-        assert any("malformed JSON" in p and "line 2" in p for p in problems)
-        assert not any("truncated" in p for p in problems)
-
-
-class TestUnknownEventType:
-    """Spec §2: readers MUST skip unknown `type` values rather than failing.
-
-    This is the rule that lets the format add an event type in a MINOR release without
-    invalidating every existing reader.
-    """
-
-    def test_is_skipped_and_reported_not_raised(self, tmp_path: Path) -> None:
-        fabricated = event(1, "gpu.allocate")  # a type from some future AgenticReplay
-        write_trace(tmp_path, [event(0, "run.start"), fabricated, event(2, "run.end")])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 2]
-        assert any("gpu.allocate" in p and "line 2" in p for p in reader.problems())
-
-    def test_does_not_manufacture_a_seq_gap(self, tmp_path: Path) -> None:
-        """The skipped event's own seq is still known, so density is intact."""
-        write_trace(tmp_path, [event(0), event(1, "gpu.allocate"), event(2)])
-        reader = TraceReader.open(tmp_path)
-        reader.events()
-        assert not any("seq" in p for p in reader.problems())
-
-    def test_a_non_string_type_is_skipped_too(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), {**event(1), "type": 7}])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0]
-        assert len(reader.problems()) == 1
-
-
-class TestSeqDensity:
-    """Spec §2.1: `seq` is a dense total order, strictly increasing, starting at 0."""
-
-    def test_reports_a_gap(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1), event(5)])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1, 5]
-        assert any("seq 5" in p and "2" in p for p in reader.problems())
-
-    def test_reports_a_log_that_does_not_start_at_zero(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(3), event(4)])
-        reader = TraceReader.open(tmp_path)
-        reader.events()
-        assert len(reader.problems()) == 1
-
-    def test_reports_a_repeated_seq(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1), event(1)])
-        reader = TraceReader.open(tmp_path)
-        assert len(reader.events()) == 3, "the events are still returned; the reader only reports"
-        assert any("seq 1" in p for p in reader.problems())
-
-    def test_a_gap_does_not_stop_the_read(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(7), event(8)])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 7, 8]
-        assert len(reader.problems()) == 1, "one gap, reported once, then resynchronised"
-
-
-class TestInvalidEvents:
-    def test_skips_an_event_that_violates_the_envelope(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), {**event(1), "actor": "robot"}, event(2)])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 2]
-        assert any("actor" in p for p in reader.problems())
-
-    def test_skips_an_event_whose_blob_reference_is_malformed(self, tmp_path: Path) -> None:
-        """Spec §2.2: a corrupt digest must not be silently accepted as opaque inline data."""
-        bad = {**event(1), "payload": {"$blob": "sha256:xyz", "bytes": 3}}
-        write_trace(tmp_path, [event(0), bad, event(2)])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 2]
-        assert any("$blob" in p for p in reader.problems())
-
-    def test_reports_a_forward_causal_edge_but_keeps_the_event(self, tmp_path: Path) -> None:
-        """Spec §2.1 requires causes < seq, but the JSON Schema does not encode it.
-
-        Dropping the event would make this reader disagree with the TypeScript one about the
-        contents of a trace, so the violation is reported instead.
-        """
-        write_trace(tmp_path, [event(0), event(1, causes=[9])])
-        reader = TraceReader.open(tmp_path)
-        assert [e.seq for e in reader.events()] == [0, 1]
-        assert any("causes" in p for p in reader.problems())
-
-
-class TestBlobs:
-    def build(self, tmp_path: Path) -> tuple[TraceReader, BlobRef]:
-        body = b'{"messages": [{"role": "user", "content": "hi"}]}'
-        hexdigest, ref = blob_of(body)
-        payload = {"$blob": ref, "bytes": len(body), "media_type": "application/json"}
-        write_trace(
-            tmp_path,
-            [event(0, "model.request", actor="agent", payload=payload)],
-            blobs={hexdigest: body},
-        )
-        reader = TraceReader.open(tmp_path)
-        return reader, BlobRef.from_json(payload)
-
-    def test_reads_a_blob_by_reference(self, tmp_path: Path) -> None:
-        reader, ref = self.build(tmp_path)
-        assert reader.blob(ref).startswith(b'{"messages"')
-
-    def test_reads_a_blob_by_prefixed_or_bare_digest(self, tmp_path: Path) -> None:
-        reader, ref = self.build(tmp_path)
-        assert reader.blob(ref.digest) == reader.blob(ref.hex) == reader.blob(ref)
-
-    def test_reports_a_missing_blob_with_the_path_it_looked_in(self, tmp_path: Path) -> None:
-        reader, ref = self.build(tmp_path)
-        (tmp_path / "blobs" / ref.shard / ref.hex).unlink()
-        with pytest.raises(BlobNotFoundError, match=ref.hex):
-            reader.blob(ref)
-
-    def test_refuses_a_digest_that_is_not_a_digest(self, tmp_path: Path) -> None:
-        """Digests reach us from a file on disk, so this check is also the traversal guard."""
-        reader, _ = self.build(tmp_path)
-        for bad in ["../../etc/passwd", "sha256:zz", "", "sha256:" + "9f" * 31]:
-            with pytest.raises(ValueError):
-                reader.blob(bad)
-
-    def test_verify_detects_a_blob_whose_content_no_longer_matches_its_name(
-        self, tmp_path: Path
-    ) -> None:
-        reader, ref = self.build(tmp_path)
-        (tmp_path / "blobs" / ref.shard / ref.hex).write_bytes(b"tampered")
-        assert reader.blob(ref) == b"tampered", "unverified reads stay byte-for-byte like the TS reader"
-        with pytest.raises(BlobIntegrityError, match="digest"):
-            reader.blob(ref, verify=True)
-
-
-class TestPayload:
-    def test_returns_none_when_there_is_no_payload(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0)])
-        reader = TraceReader.open(tmp_path)
-        assert reader.payload(reader.events()[0]) is None
-
-    def test_returns_an_inline_payload_unchanged(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, payload={"kind": "inline", "n": 3})])
-        reader = TraceReader.open(tmp_path)
-        assert reader.payload(reader.events()[0]) == {"kind": "inline", "n": 3}
-
-    def make(self, tmp_path: Path, body: bytes, media_type: str | None) -> TraceReader:
-        hexdigest, ref = blob_of(body)
-        payload: dict = {"$blob": ref, "bytes": len(body)}
-        if media_type is not None:
-            payload["media_type"] = media_type
-        write_trace(tmp_path, [event(0, payload=payload)], blobs={hexdigest: body})
-        return TraceReader.open(tmp_path)
-
-    def test_decodes_a_json_blob(self, tmp_path: Path) -> None:
-        reader = self.make(tmp_path, b'{"role": "user"}', "application/json")
-        assert reader.payload(reader.events()[0]) == {"role": "user"}
-
-    def test_decodes_a_blob_with_no_declared_media_type_as_json_when_it_parses(
-        self, tmp_path: Path
-    ) -> None:
-        reader = self.make(tmp_path, b"[1, 2, 3]", None)
-        assert reader.payload(reader.events()[0]) == [1, 2, 3]
-
-    def test_returns_bytes_for_a_non_json_media_type(self, tmp_path: Path) -> None:
-        """A dataset builder can branch on the type; a raise would abort the whole build."""
-        reader = self.make(tmp_path, b"--- a/src/auth.ts\n+++ b/src/auth.ts\n", "text/x-diff")
-        assert reader.payload(reader.events()[0]) == b"--- a/src/auth.ts\n+++ b/src/auth.ts\n"
-
-    def test_returns_bytes_when_a_blob_claims_json_but_is_not(self, tmp_path: Path) -> None:
-        reader = self.make(tmp_path, b"\x00\x01 not json", "application/json")
-        assert reader.payload(reader.events()[0]) == b"\x00\x01 not json"
-
-    def test_propagates_a_missing_blob(self, tmp_path: Path) -> None:
-        reader = self.make(tmp_path, b"{}", "application/json")
-        for path in (tmp_path / "blobs").rglob("*"):
-            if path.is_file():
-                path.unlink()
-        with pytest.raises(BlobNotFoundError):
-            reader.payload(reader.events()[0])
-
-
-class TestVerifyIntegrity:
-    """Spec §6: readers SHOULD verify the root and MUST report, not repair, a mismatch."""
-
-    def test_verifies_a_sealed_run(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1)])
-        ok, expected, actual = TraceReader.open(tmp_path).verify_integrity()
-        assert ok is True
-        assert expected == actual == hashlib.sha256((tmp_path / "events.jsonl").read_bytes()).hexdigest()
-
-    def test_reports_a_mismatch_and_repairs_nothing(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0), event(1)])
-        path = tmp_path / "events.jsonl"
-        before = files_in(tmp_path)
-        path.write_text(path.read_text(encoding="utf-8").replace('"turn":0', '"turn":9'), encoding="utf-8")
-        tampered = path.read_bytes()
-
-        ok, expected, actual = TraceReader.open(tmp_path).verify_integrity()
-        assert ok is False
-        assert expected != actual
-        assert expected == hashlib.sha256(before["events.jsonl"][1]).hexdigest()
-        assert actual == hashlib.sha256(tampered).hexdigest()
-        assert path.read_bytes() == tampered, "the reader must not repair the file"
-
-    def test_reports_an_unsealed_run_rather_than_claiming_success(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0)], seal=False)
-        ok, expected, actual = TraceReader.open(tmp_path).verify_integrity()
-        assert ok is False
-        assert expected == ""
-        assert len(actual) == 64
-
-    def test_reports_a_missing_events_file(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0)])
-        (tmp_path / "events.jsonl").unlink()
-        ok, _expected, actual = TraceReader.open(tmp_path).verify_integrity()
-        assert ok is False
-        assert actual == ""
-
-
-class TestProblems:
-    def test_are_populated_without_an_explicit_read_pass(self, tmp_path: Path) -> None:
-        """Returning [] for a trace nobody has read yet would hide exactly what this reports."""
-        write_trace(tmp_path, [event(0), event(1, "gpu.allocate")])
-        assert len(TraceReader.open(tmp_path).problems()) == 1
-
-    def test_do_not_accumulate_across_reads(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, "gpu.allocate")])
-        reader = TraceReader.open(tmp_path)
-        reader.events()
-        reader.events()
-        assert len(reader.problems()) == 1
-
-    def test_are_returned_as_a_copy(self, tmp_path: Path) -> None:
-        write_trace(tmp_path, [event(0, "gpu.allocate")])
-        reader = TraceReader.open(tmp_path)
-        reader.problems().clear()
-        assert len(reader.problems()) == 1
-
-
-class TestReadOnly:
-    def test_reading_a_trace_never_writes_to_it(self, tmp_path: Path) -> None:
-        """The read-only boundary is the reason this SDK exists in a second language at all."""
-        body = b'{"a": 1}'
-        hexdigest, ref = blob_of(body)
-        write_trace(
-            tmp_path,
-            [
-                event(0, "run.start"),
-                event(1, "fs.snapshot", attrs={"tree": "t0"}),
-                event(2, payload={"$blob": ref, "bytes": len(body), "media_type": "application/json"}),
-            ],
-            blobs={hexdigest: body},
-        )
-        before = files_in(tmp_path)
-
-        reader = TraceReader.open(tmp_path)
-        events = reader.events()
-        list(reader.stream())
-        reader.payload(events[2])
-        reader.blob(ref)
-        reader.verify_integrity()
-        reader.problems()
-
-        assert files_in(tmp_path) == before
-
-    def test_exposes_no_write_api(self) -> None:
-        forbidden = {"write", "append", "put", "record", "redact", "fork", "delete"}
-        assert forbidden.isdisjoint(dir(TraceReader))

package/python-langgraph/README.md

@@ -1,159 +0,0 @@
-# agenticreplay-langgraph
-
-Record a LangGraph run's own structure — which node ran, in which superstep, and how it ended —
-into an [AgenticReplay](https://github.com/askdkc/AgenticReplay) trace.
-
-```console
-pip install agenticreplay-langgraph
-```
-
-That is the whole setup. `agenticreplay record` attaches it to a graph you have not edited; there is no
-callback to register, no `with_config`, and no import in your code.
-
-```console
-agenticreplay record generic-openai -- python your_graph.py
-```
-
-## What it adds, and what it does not
-
-agenticreplay records model traffic at a proxy, and every claim it makes about capture comes from there.
-This package is not needed for that: a LangGraph run recorded without it is complete in the sense
-the rest of the project means. What it adds is the part a proxy structurally cannot see.
-
-The wire carries the conversation and not the graph. Searching a recorded three-node run for the
-node names, the graph's name, `langgraph_node` and `langgraph_step` finds none of them in any
-request:
-
-| the trace can answer | without | with |
-| --- | --- | --- |
-| which nodes ran, and in which superstep | no | yes |
-| that a node ran at all, when it called no model | no | yes |
-| that two calls were one parallel superstep, not two turns | no | yes |
-| when each node began and ended | no | yes |
-
-The second row is the common shape rather than an edge case. Validators, state reducers, routers
-and writers make no model call, so a proxy sees a graph with those nodes and a graph without them
-as the same run. Recorded with this package, a graph of `plan → validate → answer` against a stub
-origin produces:
-
-```
-03:24:45.102  graph.node.start   plan
-03:24:45.233  model.request
-03:24:45.235  model.response
-03:24:45.239  graph.node.end     plan
-03:24:45.240  graph.node.start   validate      ← no request of any kind
-03:24:45.241  graph.node.end     validate
-03:24:45.241  graph.node.start   answer
-03:24:45.254  graph.node.end     answer
-```
-
-**What it does not do is attribute a model call to a node by timestamp alone**, and the reason is
-on agenticreplay's side rather than here. A node record carries the instant the callback fired — measured
-against the agent's own clock, exactly. A `model.request` is stamped when agenticreplay *persists* it, which
-is after the response and after a workspace snapshot: measured 95 ms late on one call and 31 ms on
-the next. The node boundaries are trustworthy; a call within about a tenth of a second of one can
-fall on the wrong side of it.
-
-## What is written
-
-Two record types, and from each only the fields the reader consumes:
-
-| record | fields |
-| --- | --- |
-| `LangGraphNodeStart` | `node`, `step`, `run_id`, `parent_run_id`, `started_at` |
-| `LangGraphNodeEnd` | `node`, `step`, `run_id`, `ended_at`, and `error` when the node raised |
-
-Nothing else. No state, no inputs, no outputs, no messages, no tool arguments, and no exception
-*message* — only the exception's class name. The model exchanges are left to the proxy, which
-already holds them byte for byte; a second copy in a file agenticreplay does not redact on the way in would
-be a lossier duplicate in a place nothing scrubs.
-
-`step` is the superstep, which is per graph rather than per run: a subgraph's node reports its own,
-so two records can share a step without being concurrent. `parent_run_id` is what separates those,
-and it is how two nodes of one parallel fan-out are told apart from two consecutive turns.
-
-## How a node is recognised
-
-This is the whole design, and it is also what keeps the package safe.
-
-`on_chain_start` fires for everything a graph runs. At that moment a node, a runnable *inside* a
-node, a subgraph and a conditional-edge function all look alike — same inherited `langgraph_node`,
-same `langgraph_step`, and an arbitrary `name`. Measured on one graph: `name='INNER-RUNNABLE'`
-carrying `langgraph_node='first'`, `name='router'` carrying `langgraph_node='validate_only'`, and
-`name='the_graph'` carrying no `langgraph_node` at all. Reporting on `name` alone reports all four.
-
-So a node is reported only when the `name` kwarg **equals** `metadata['langgraph_node']` — compared,
-never copied. `langgraph_node` is the name the graph's author wrote in `add_node(...)`, while `name`
-is whatever the caller supplied, including
-
-```python
-node.with_config({"run_name": f"lookup for {customer.email}"})
-```
-
-The two are equal only for an author-defined node, so a runtime string cannot reach the transport
-through this path. LangGraph's own `__start__` and `__end__` markers are filtered as well: they are
-reported exactly like nodes, and nobody wrote them.
-
-## Inert unless agenticreplay is recording
-
-Everything keys off `AGENTICREPLAY_AGENT_SPANS`, which only `agenticreplay record` sets. With it unset the package
-registers nothing, opens nothing and costs nothing, which is what makes it safe to leave installed.
-
-It declares **no dependencies** — not langgraph, not langchain-core. Installing a framework as a
-side effect of installing a debugging aid is the kind of thing that makes people uninstall the
-debugging aid, and `agenticreplay record` puts this package's bootstrap in front of every Python process a
-recording starts, `python --version` included. Importing the module that holds langchain-core's
-hook registry costs **617 ms** against an interpreter that starts in about 50, so `install()` arms
-a `sys.meta_path` finder and returns; the registration happens the first time anything under
-`langgraph` is imported, in a process already paying a second for it.
-
-## Using it explicitly
-
-Supported, for anyone who would rather be. `install()` returns whether it did anything, and is
-false — quietly — when agenticreplay is not recording or the hook is already registered.
-
-```python
-from agenticreplay_langgraph import install
-
-install()
-```
-
-To supply your own handler instance, set the context variable langchain-core offers:
-
-```python
-from agenticreplay_langgraph import HANDLER_VAR, AgenticReplayCallbackHandler
-
-HANDLER_VAR.set(AgenticReplayCallbackHandler())
-```
-
-## The langchain-core interface it implements
-
-`AgenticReplayCallbackHandler` is **not** a subclass of `BaseCallbackHandler`, deliberately: importing
-langchain-core to define the class would make this module unimportable without it, and the point is
-that it is inert when langchain-core is absent. langchain-core checks the attributes, not the base
-class, and `_configure` type-checks with `isinstance(handler, handler_class)` against the class it
-was handed — which is this one.
-
-| attribute | value | why |
-| --- | --- | --- |
-| `on_chain_start` / `on_chain_end` / `on_chain_error` | implemented | node boundaries, and how one ended |
-| `ignore_chain` | `False` | the only callbacks this wants |
-| `ignore_llm`, `ignore_chat_model`, `ignore_retriever`, `ignore_agent`, `ignore_retry`, `ignore_custom_event` | `True` | keeps it out of the token and tool hot path |
-| `run_inline` | `True` | without it an `ainvoke` runs the callback on the default executor, and the timestamps say when it was scheduled |
-| `raise_error` | `False` | a callback must never take the graph down |
-
-Every `ignore_*` the base class defines is present, including the ones set to `False`: the
-dispatcher reads them with a bare `getattr`, so a missing one is an `AttributeError` per callback,
-which langchain-core logs and swallows. Measured, omitting `ignore_chain` gave a graph that ran to
-completion, printed four `Error in ... callback` lines, and recorded nothing — a silent miss. A test
-compares the two sets so a langchain-core release that adds an eighth is caught by a test rather
-than by an empty trace.
-
-`__init__` does nothing at all, and that is load-bearing: `_configure` constructs a handler on every
-configure call, unguarded, before deciding whether one is already present — measured, one trivial
-`invoke()` constructs two. A handler whose `__init__` raised made an ordinary `app.invoke()` raise
-the same exception, so nothing here opens a file, reads the environment or joins a path.
-
-## Licence
-
-Apache-2.0.

package/python-langgraph/agenticreplay_langgraph/__init__.py

@@ -1,21 +0,0 @@
-"""Record which LangGraph node did what, into an AgenticReplay trace.
-
-Inert unless agenticreplay is recording: everything here keys off the `AGENTICREPLAY_AGENT_SPANS` environment
-variable, which only `agenticreplay record` sets. See `handler` for what it captures and why it leaves the
-model exchanges to the proxy, and `hook` for how it attaches to a graph nobody edited.
-"""
-
-from .handler import PACKAGE, SPAN_END, SPAN_START, SPANS_ENV, AgenticReplayCallbackHandler
-from .hook import HANDLER_VAR, install, uninstall
-
-__all__ = [
-    "HANDLER_VAR",
-    "PACKAGE",
-    "SPANS_ENV",
-    "SPAN_END",
-    "SPAN_START",
-    "AgenticReplayCallbackHandler",
-    "install",
-    "uninstall",
-]
-__version__ = "0.1.0"