agent-tracegraph 0.3.1__tar.gz → 0.4.0__tar.gz

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/CHANGELOG.md

@@ -6,6 +6,31 @@ The **artifact** schema version and the **report**/**review-candidate** JSON sch
 separate contracts from this version number; changes to any of them are called out
 explicitly.
 
+## 0.4.0 - 2026-10-14
+
+### Added
+
+- **LangGraph tasks paused by `interrupt()` are reported.** A task whose only write on the
+  thread's newest root checkpoint is `__interrupt__` — it paused and the history holds no
+  resume and no result — becomes an `unset` step with the new source value `interrupt`,
+  linked by `CAUSED_BY` to that checkpoint and named by the same task-id reconstruction as
+  failed tasks. The step describes the recorded history, not whether LangGraph would resume
+  the task now. An interrupt recorded beside a resume or an error and no result is ambiguous
+  in the checkpoint (under LangGraph 1.2.2 a resumed task that wrote nothing looks exactly
+  like one paused twice; 1.2.15 marks it finished), so it is disclosed at ingest instead. Trace `status` is unchanged: a pause is not an error.
+- **Artifact schema version 5**, stamped by content: only an artifact carrying an
+  `interrupt` step declares it, so every other artifact serializes byte for byte as before.
+  0.3.1 and earlier refuse a version 5 artifact by name; this build reads versions 1 to 5,
+  and still rejects an envelope that declares less than its content needs.
+
+### Known limitations
+
+- Tasks scheduled but never started — the recursion limit, a killed process, an
+  `interrupt_before`/`interrupt_after` breakpoint — leave no write and are still not
+  reported. Telling them apart from finished work needs the compiled graph.
+- An interrupt inside a subgraph is reported as the subgraph's node at the root, not as the
+  node inside the subgraph that paused.
+
 ## 0.3.1 - 2026-10-13
 
 ### Fixed

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.3.1
+Version: 0.4.0
 Summary: Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph.
 Project-URL: Homepage, https://github.com/memtomem/tracegraph
 Project-URL: Repository, https://github.com/memtomem/tracegraph
@@ -289,9 +289,11 @@ and any change to them is called out in the [changelog](CHANGELOG.md).
 
 Known limits:
 
-- A LangGraph task that was scheduled but left no result and no recorded error (a run
-  paused by `interrupt()`, stopped by the recursion limit, or killed) is not reported, so
-  such a run reads `ok` unless some other step recorded an error.
+- A LangGraph task that was scheduled but never started (a run stopped by the recursion
+  limit, killed, or held at an `interrupt_before`/`interrupt_after` breakpoint) leaves no
+  write and is not reported, so such a run reads `ok` unless some other step recorded an
+  error. A task paused by `interrupt()` *is* reported (below), but only at the root graph:
+  the subgraph node is named, not the node inside it that paused.
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
@@ -376,9 +378,16 @@ cancels its siblings and records that through the same channel; a cancelled task
 as an `unset` step with no message, because it was torn down rather than at fault. Only the
 latest persisted error survives per task, so repeated attempts are not reconstructed, and
 `Send` packets are nameable only where `langgraph.types` is importable — an ordinary install
-discloses them instead. An artifact whose derived tree relies on EdgeOrigin precedence declares
-artifact `schema_version` 4; otherwise, an artifact carrying derived task steps declares
-`schema_version` 3, and artifacts without them still serialize as version 2, byte for byte.
+discloses them instead. A task that called `interrupt()` and whose only write on the thread's
+newest root checkpoint is that interrupt becomes an `unset` step with source `interrupt` under
+that checkpoint: the recorded history holds no resume and no result for it. That describes the
+history, not whether LangGraph would resume the task today. An interrupt recorded together with
+a resume or an error and no result is ambiguous in the checkpoint itself — under LangGraph 1.2.2
+a task resumed with nothing to write looks exactly like one paused a second time — so it is
+disclosed at ingest, not reported. An artifact carrying interrupt steps declares artifact `schema_version` 5; one
+whose derived tree relies on EdgeOrigin precedence declares 4; otherwise, an artifact carrying
+derived task steps declares `schema_version` 3, and artifacts without them still serialize as
+version 2, byte for byte.
 Missing observed errors still do not
 prove success: an artifact ingested by an older build, or one using an unrecognized checkpoint
 layout, carries no derived step and looks exactly like a clean run, which is why the capture

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/README.md

@@ -258,9 +258,11 @@ and any change to them is called out in the [changelog](CHANGELOG.md).
 
 Known limits:
 
-- A LangGraph task that was scheduled but left no result and no recorded error (a run
-  paused by `interrupt()`, stopped by the recursion limit, or killed) is not reported, so
-  such a run reads `ok` unless some other step recorded an error.
+- A LangGraph task that was scheduled but never started (a run stopped by the recursion
+  limit, killed, or held at an `interrupt_before`/`interrupt_after` breakpoint) leaves no
+  write and is not reported, so such a run reads `ok` unless some other step recorded an
+  error. A task paused by `interrupt()` *is* reported (below), but only at the root graph:
+  the subgraph node is named, not the node inside it that paused.
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
@@ -345,9 +347,16 @@ cancels its siblings and records that through the same channel; a cancelled task
 as an `unset` step with no message, because it was torn down rather than at fault. Only the
 latest persisted error survives per task, so repeated attempts are not reconstructed, and
 `Send` packets are nameable only where `langgraph.types` is importable — an ordinary install
-discloses them instead. An artifact whose derived tree relies on EdgeOrigin precedence declares
-artifact `schema_version` 4; otherwise, an artifact carrying derived task steps declares
-`schema_version` 3, and artifacts without them still serialize as version 2, byte for byte.
+discloses them instead. A task that called `interrupt()` and whose only write on the thread's
+newest root checkpoint is that interrupt becomes an `unset` step with source `interrupt` under
+that checkpoint: the recorded history holds no resume and no result for it. That describes the
+history, not whether LangGraph would resume the task today. An interrupt recorded together with
+a resume or an error and no result is ambiguous in the checkpoint itself — under LangGraph 1.2.2
+a task resumed with nothing to write looks exactly like one paused a second time — so it is
+disclosed at ingest, not reported. An artifact carrying interrupt steps declares artifact `schema_version` 5; one
+whose derived tree relies on EdgeOrigin precedence declares 4; otherwise, an artifact carrying
+derived task steps declares `schema_version` 3, and artifacts without them still serialize as
+version 2, byte for byte.
 Missing observed errors still do not
 prove success: an artifact ingested by an older build, or one using an unrecognized checkpoint
 layout, carries no derived step and looks exactly like a clean run, which is why the capture

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # the schema `kind` constants and the TRACEGRAPH_* environment variables — those are package
 # identity, not distribution identity, and renaming them would break published contracts.
 name = "agent-tracegraph"
-version = "0.3.1"
+version = "0.4.0"
 description = "Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph."
 readme = "README.md"
 requires-python = ">=3.12"

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/src/tracegraph/adapters/langgraph_checkpoint.py

@@ -54,6 +54,17 @@ steps carrying no message, and only the task that actually raised is an ``ERROR`
 Only the *latest* persisted error survives per task id — a fail/fail/succeed sequence leaves
 one record — so attempts are never reconstructed. Errors are recorded wherever they appear;
 this module does not infer anything from their *absence*.
+
+Interrupted tasks
+-----------------
+A node that calls ``interrupt()`` leaves an ``__interrupt__`` pending write on the checkpoint
+that scheduled it, and LangGraph resumes from the thread's newest root checkpoint. A task whose
+*only* write on that checkpoint is ``__interrupt__`` therefore never received a resume or
+produced a result, and becomes an ``UNSET`` step with ``source=INTERRUPT``. That is a statement
+about the recorded history, not a prediction that LangGraph would resume it now. Tasks that were
+scheduled but never started (the recursion limit, a killed process, a static breakpoint) leave no
+write at all and are not reported: telling them apart from finished work needs the compiled
+graph, which this adapter does not have.
 """
 
 from __future__ import annotations
@@ -108,6 +119,11 @@ _CONFIG_FIELDS = {name: TypeAdapter(str) for name in ("thread_id", "checkpoint_n
 # them — so copying them is safer than importing a private module that may move.
 _ERROR = "__error__"
 _ERROR_SOURCE_NODE = "__error_source_node__"
+_INTERRUPT = "__interrupt__"
+_RESUME = "__resume__"
+#: Writes that can sit beside an ``__interrupt__`` without recording whether the task is still
+#: paused. Any other write is a result, and the task is no longer waiting.
+_UNDECIDED_WITH_INTERRUPT = frozenset({_INTERRUPT, _RESUME, _ERROR, _ERROR_SOURCE_NODE})
 _START = "__start__"
 _TASKS = "__pregel_tasks"
 _PULL = "__pregel_pull"
@@ -320,6 +336,11 @@ class LangGraphCheckpointAdapter:
         ingest_warnings = self._derive_task_steps(
             trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges
         )
+        ingest_warnings.extend(
+            self._derive_interrupt_steps(
+                trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges
+            )
+        )
         if malformed_writes:
             ingest_warnings.append(
                 f"{malformed_writes} pending write(s) are not a (task id, channel, value) "
@@ -439,6 +460,92 @@ class LangGraphCheckpointAdapter:
             )
         return warnings
 
+    @classmethod
+    def _derive_interrupt_steps(
+        cls,
+        trace_id: str,
+        steps: dict[str, Step],
+        checkpoints: dict[str, dict],
+        key_by_step_id: dict[str, _CheckpointKey],
+        original_seq: dict[str, int],
+        writes_by_step: dict[str, dict[str, list[tuple[str, Any]]]],
+        edges: list[Edge],
+    ) -> list[str]:
+        """Add one UNSET step per task the head checkpoint records as interrupted, never resumed.
+
+        Only the thread's head — the newest root checkpoint, which is what LangGraph itself
+        resumes from — is read. An ``__interrupt__`` write on any earlier checkpoint was resumed,
+        forked past, or abandoned, and is history rather than an open pause.
+
+        A task is reported only when ``__interrupt__`` is its *only* write. Anything else that
+        accompanies it leaves the task's state unrecorded, and it is disclosed rather than
+        guessed: under LangGraph 1.2.2 a resumed task that returned nothing leaves
+        ``{__interrupt__, __resume__}``, exactly like one that reached a second ``interrupt()``
+        (LangGraph overwrites the interrupt in place; 1.2.15 adds ``__no_writes__`` to the
+        first, which then reads as finished); a failure followed by a retry that interrupts leaves the same
+        ``{__error__, __interrupt__}`` as the reverse order, because savers keep no order.
+        """
+        root_ids = [sid for sid, (ns, _) in key_by_step_id.items() if ns == _ROOT_NS]
+        if not root_ids:
+            return []
+        head_id = max(root_ids, key=lambda sid: checkpoints[sid]["id"])
+        head = steps[head_id]
+        cp = checkpoints[head_id]
+        _, cid = key_by_step_id[head_id]
+        warnings: list[str] = []
+        undecided = 0
+        for task_id, task_writes in (writes_by_step.get(head_id) or {}).items():
+            if task_id == _NULL_TASK_ID:
+                continue
+            channels = {channel for channel, _ in task_writes}
+            if _INTERRUPT not in channels:
+                continue
+            if channels != {_INTERRUPT}:
+                if channels <= _UNDECIDED_WITH_INTERRUPT:
+                    undecided += 1
+                continue
+            name = cls._resolve_task_name(cp, _ROOT_NS, original_seq[head_id], task_id, task_writes)
+            if name is None:
+                warnings.append(
+                    f"checkpoint {cid}: interrupted task {task_id} could not be attributed to a "
+                    "node; no candidate reproduced its task id, which is also what a change in "
+                    "LangGraph's task-id algorithm would look like."
+                )
+            derived_id = f"{head_id}#interrupt:{task_id}"
+            if derived_id in steps:
+                raise ValueError(
+                    f"derived interrupt step id {derived_id!r} collides with a checkpoint id "
+                    "or another derived step"
+                )
+            steps[derived_id] = Step(
+                step_id=derived_id,
+                trace_id=trace_id,
+                seq=head.seq + 1,
+                ts=head.ts,
+                kind=StepKind.TOOL if name and _looks_like_tool_node(name) else StepKind.CHAIN,
+                source=StepSource.INTERRUPT,
+                name=name,
+                # The task has no outcome yet. The interrupt's value is whatever the node asked
+                # its caller, which is user content, so it is not carried as a message.
+                status=StepStatus.UNSET,
+            )
+            edges.append(
+                Edge(
+                    type=EdgeType.CAUSED_BY,
+                    src=derived_id,
+                    dst=head_id,
+                    # LangGraph keys the write to the head checkpoint itself.
+                    origin=EdgeOrigin.CHECKPOINT_PARENT,
+                )
+            )
+        if undecided:
+            warnings.append(
+                f"checkpoint {cid}: {undecided} task(s) recorded an interrupt together with a "
+                "resume or an error and no result; the checkpoint does not record whether each "
+                "is still paused, so none is reported as interrupted."
+            )
+        return warnings
+
     @staticmethod
     def _writes_by_task(pending_writes: Any) -> tuple[dict[str, list[tuple[str, Any]]], int]:
         """Group a checkpoint's pending writes by task id, in first-seen order.

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/src/tracegraph/artifact.py

@@ -19,13 +19,13 @@ from tracegraph.input_validation import loads as json_loads
 from tracegraph.model import NormalizedTrace, StepSource
 
 #: Bump when the on-disk shape changes incompatibly.
-ARTIFACT_SCHEMA_VERSION = 4
+ARTIFACT_SCHEMA_VERSION = 5
 
 #: Versions this build can read. 1 needs a migration (see ``_migrate_v1``); 2 -> 3 is the
 #: identity, because 3 adds only a new ``Step.source`` value and changes nothing existing.
 #: 4 signals that TREE_PARENT was derived under EdgeOrigin precedence rather than
-#: legacy temporal-only selection.
-_READABLE_VERSIONS = (1, 2, 3, ARTIFACT_SCHEMA_VERSION)
+#: legacy temporal-only selection. 5 adds only the ``interrupt`` ``Step.source`` value.
+_READABLE_VERSIONS = (1, 2, 3, 4, ARTIFACT_SCHEMA_VERSION)
 
 
 def _required_version(nt: NormalizedTrace) -> int:
@@ -38,6 +38,9 @@ def _required_version(nt: NormalizedTrace) -> int:
     bump would invalidate digests already exported in review-candidate reports for artifacts
     whose content did not change at all.
 
+    * An artifact that carries an interrupt step is stamped 5, whatever its projection: a
+      v5 reader also reads the v4 projection, and an older reader would otherwise fail on
+      the unknown enum value instead of refusing the version by name.
     * An artifact whose derived TREE_PARENT relies on EdgeOrigin priority is stamped 4,
       so older readers (which used temporal-only parent selection) refuse it with an
       explicit "unsupported artifact schema_version 4" rather than failing canonical
@@ -47,6 +50,9 @@ def _required_version(nt: NormalizedTrace) -> int:
     """
     from tracegraph.normalize import requires_origin_priority_projection
 
+    interrupt = StepSource.INTERRUPT
+    if any(step.source is interrupt for step in nt.steps):
+        return 5
     if requires_origin_priority_projection(nt):
         return 4
     task = StepSource.TASK

{agent_tracegraph-0.3.1 → agent_tracegraph-0.4.0}/src/tracegraph/model.py

@@ -54,10 +54,15 @@ class StepKind(str, Enum):
 class StepSource(str, Enum):
     """How the step entered the trace (mirrors LangGraph ``metadata.source``).
 
-    ``TASK`` is the one value that does *not* come from ``metadata.source``: it marks a step
+    ``TASK`` and ``INTERRUPT`` do *not* come from ``metadata.source``. ``TASK`` marks a step
     derived from a checkpoint's **pending writes** (one LangGraph task) rather than from a
     checkpoint itself. It is explicit provenance, not a naming convention — ``step_id`` is an
     unrestricted string, so nothing about an id may be read as evidence of how a step was made.
+
+    ``INTERRUPT`` is likewise derived from pending writes: a LangGraph task that called ``interrupt()`` and
+    for which the recorded history holds no resume and no result. It states what the
+    checkpoints record, not that LangGraph would resume the task today — a thread re-run under
+    a revised graph can finish without writing a checkpoint, leaving the record unchanged.
     """
 
     INPUT = "input"
@@ -65,6 +70,7 @@ class StepSource(str, Enum):
     UPDATE = "update"
     FORK = "fork"
     TASK = "task"
+    INTERRUPT = "interrupt"
 
 
 class StepStatus(str, Enum):