agentdebugx 0.2.10__tar.gz → 0.2.12__tar.gz

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdebugx
-Version: 0.2.10
+Version: 0.2.12
 Summary: Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`.
 License: MIT
 License-File: LICENSE
@@ -29,6 +29,7 @@ Provides-Extra: all
 Provides-Extra: crewai
 Provides-Extra: hub-hf
 Provides-Extra: langgraph
+Provides-Extra: openai-agents
 Provides-Extra: openhands
 Provides-Extra: otel
 Provides-Extra: ui

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/docs/23_status_v0_2.md

@@ -28,9 +28,13 @@ the forward-looking plan; this doc is the rear-view mirror.
 | Recovery | `agentdebug.recovery.CriticRecoverer` + `VerifierSpec` registry | ✅ **new 0.2.3** | 5 family-matched verifier templates; dedup + custom-override |
 | Recovery | `agentdebug.recovery.SelfRefineLoop` | ✅ **new 0.2.9** | scripted-LLM happy + silent-LLM safe + multi-iter; per-finding generator→critic→refiner |
 | Recovery | `agentdebug.recovery.AutoManualRules` (+ `apply()`) | ✅ **new 0.2.9** | no-LLM fallback + LLM rule-distill + idempotent apply + multi-rule append |
+| Recovery | `agentdebug.recovery.SagaRollback` + `Compensator` registry | ✅ **new 0.2.12** | reverse-order suggestion + skip-errored-tools + apply() invokes registered compensation + raises on unknown tool / missing event |
+| Adapter | `agentdebug.adapters.openai_agents.OpenAIAgentsBridge` (TracingProcessor) | ✅ **new 0.2.12** | doctor-status when sdk absent + import-error path + bridge translates function/generation/handoff/unknown spans + context manager attach/detach |
 | DeepDebug | `agentdebug.deep.DeepDebugAnalyzer` | ✅ stable | full loop + silent LLM |
 | Cascade view | `agentdebug.traceback.format_traceback` | ✅ stable | cascade + step-order + ANSI + empty |
 | Detectors | `agentdebug.detectors.RepeatedToolCall / RepeatedState / StepCountLimit` | ✅ **new 0.2.2** | threshold + window + budget |
+| Detectors | `agentdebug.detectors.TopicDriftDetector` (embedding cosine vs goal) | ✅ **new 0.2.11** | stub-embedder ranking + no-goal short-circuit + embedder-raises safe + threshold boundary |
+| LLM client | `agentdebug.llm.OpenAICompatClient.embed()` (+ `EmbeddingClient` Protocol) | ✅ **new 0.2.11** | mocked-httpx POST /v1/embeddings + empty-input short-circuit |
 | Hub bundle | `agentdebug.hub.Bundle / pack_bundle / unpack_bundle` | ✅ stable | round-trip |
 | Hub scrubber | `agentdebug.hub.Scrubber` | ✅ stable | 12 redactions + idempotent |
 | Hub backends | `LocalHubBackend`, `GitHubBackend`, `HuggingFaceBackend` | ✅ stable | local-bare-git + local |
@@ -49,14 +53,12 @@ across 32 source files.
 
 | Doc | Component | Why deferred | Realistic ship |
 |---|---|---|---|
-| [06_detectors.md](./06_detectors.md) | `trajectory_perplexity` (TrajAD) | needs token-level LM perplexity API or embedding model + baseline calibration | v0.3 |
-| [06_detectors.md](./06_detectors.md) | `topic_drift` (embedding cosine) | needs embedding client; consider reusing `OpenAICompatClient` `/embeddings` | v0.3 |
+| [06_detectors.md](./06_detectors.md) | `trajectory_perplexity` (TrajAD) | needs token-level LM perplexity API; v0.3 |
 | [06_detectors.md](./06_detectors.md) | LTL spec monitors | requires user-supplied spec or LLM-synthesized monitors; gated on RV research | v1.2 |
 | [07_attribution.md](./07_attribution.md) | `CounterfactualAttributor` — *real* replay variant | true re-rollout requires framework-specific replay surface; the v0.2.7 LLM-simulated variant ships now, the real-replay variant is gated on adapter support (LangGraph checkpointer / OpenHands rewind) | v0.4 |
 | [07_attribution.md](./07_attribution.md) | `SBFLAttributor` — *corpus* | shipped in 0.2.8 (`tarantula`/`ochiai`/`dstar`); awaiting paired-trace adoption to gather a useful corpus in production | corpus tooling deferred to v0.4 |
 | [07_attribution.md](./07_attribution.md) | `DeltaDebugAttributor` (Zeller) | same replay constraint | v0.3 |
 | [08_recovery.md](./08_recovery.md) | `LangGraphRewind` | depends on LangGraph checkpointer; ships when we have a real LangGraph user | v0.3 |
-| [08_recovery.md](./08_recovery.md) | `SagaRollback` | needs compensation registry on tool definitions; new schema | v0.3 |
 | [08_recovery.md](./08_recovery.md) | `MCTSBranchExploration` (LATS) | heavy; v2 feature | v2.0 |
 | [09_error_database.md](./09_error_database.md) | DuckDB analytical + Parquet archive | optional; Hub bundles already give per-project corpus | v0.3 |
 | [09_error_database.md](./09_error_database.md) | Vector similarity search | needs embedding model + index choice | v0.3 |

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentdebugx"
-version = "0.2.10"
+version = "0.2.12"
 description = "Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`."
 authors = ["ULab @ UIUC <ulab@illinois.edu>"]
 license = "MIT"
@@ -53,6 +53,7 @@ httpx = ">=0.24,<1.0"
 [tool.poetry.extras]
 langgraph = ["langchain-core"]
 crewai = ["crewai"]
+openai-agents = ["openai-agents"]
 otel = ["opentelemetry-api", "opentelemetry-sdk"]
 ui = ["fastapi", "uvicorn"]
 hub-hf = ["huggingface_hub"]
@@ -60,6 +61,7 @@ openhands = ["openhands-ai"]
 all = [
     "langchain-core",
     "crewai",
+    "openai-agents",
     "opentelemetry-api",
     "opentelemetry-sdk",
     "fastapi",

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/src/agentdebug/__init__.py

@@ -28,6 +28,7 @@ from agentdebug.detectors import (
     RepeatedStateDetector,
     RepeatedToolCallDetector,
     StepCountLimitDetector,
+    TopicDriftDetector,
     default_detectors,
     run_detectors,
 )
@@ -46,10 +47,13 @@ from agentdebug.recorder import AgentDebug, TraceSession
 from agentdebug.recovery import (
     DEFAULT_VERIFIERS,
     AutoManualRules,
+    CompensationSpec,
+    Compensator,
     CriticRecoverer,
     FixProposal,
     Recoverer,
     ReflexionSuggestion,
+    SagaRollback,
     SelfRefineLoop,
     VerifierSpec,
 )
@@ -71,6 +75,8 @@ __all__ = [
     'AutoManualRules',
     'BinarySearchAttributor',
     'CascadeFrame',
+    'CompensationSpec',
+    'Compensator',
     'CounterfactualAttributor',
     'CriticRecoverer',
     'DEFAULT_VERIFIERS',
@@ -79,9 +85,11 @@ __all__ = [
     'EnsembleAttributor',
     'RepeatedStateDetector',
     'RepeatedToolCallDetector',
+    'SagaRollback',
     'SBFLAttributor',
     'SelfRefineLoop',
     'StepByStepAttributor',
+    'TopicDriftDetector',
     'StepCountLimitDetector',
     'VerifierSpec',
     'build_cascade',
@@ -108,4 +116,4 @@ __all__ = [
     'get_failure_mode',
 ]
 
-__version__ = '0.2.10'
+__version__ = '0.2.12'

agentdebugx-0.2.12/src/agentdebug/adapters/openai_agents.py

@@ -0,0 +1,239 @@
+"""OpenAI Agents SDK adapter — bridge `agents.tracing` into AgentDebug.
+
+The OpenAI Agents SDK (``openai-agents``) emits typed spans through its own
+tracing system (not OpenTelemetry — though there are community OTel bridges).
+The integration point is :class:`agents.tracing.TracingProcessor`: subclass
+it, register via ``add_trace_processor``, and you receive ``on_span_start`` /
+``on_span_end`` for every span the SDK creates (``generation``, ``function``,
+``agent``, ``guardrail``, ``handoff``, audio, …).
+
+This module ships ``OpenAIAgentsBridge``, which converts each span end into
+an :class:`agentdebug.models.AgentEvent` and records it on a long-lived
+:class:`AgentTrajectory`. The ``agents`` package is imported lazily, so this
+module is safe to import without the SDK installed.
+
+Usage::
+
+    from agentdebug import AgentDebug, SQLiteTraceStore
+    from agentdebug.adapters.openai_agents import OpenAIAgentsBridge
+
+    debugger = AgentDebug(store=SQLiteTraceStore('.agentdebug/errors.sqlite'))
+    trajectory = debugger.start_trace(goal='answer the user', framework='openai-agents')
+
+    with OpenAIAgentsBridge(debugger, trajectory):
+        from agents import Agent, Runner
+        agent = Agent(name='Assistant', instructions='Be concise.')
+        Runner.run_sync(agent, 'What is 2+2?')
+
+    debugger.finish_trace(trajectory, success=True)
+"""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any, List, Literal, Optional, Type
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+from agentdebug.models import AgentTrajectory, EventType
+from agentdebug.recorder import AgentDebug
+
+LOG = logging.getLogger('agentdebug.adapters.openai_agents')
+
+
+def _import_agents_tracing() -> Any:
+    try:
+        from agents import tracing as _tracing
+    except ImportError as exc:
+        raise ImportError(
+            'OpenAIAgentsBridge requires the `openai-agents` package. '
+            "Install with `pip install 'agentdebugx[openai-agents]'` or "
+            "`pip install openai-agents`."
+        ) from exc
+    return _tracing
+
+
+# Span-type names the SDK emits; map each to the most representative
+# AgentDebugX EventType. Names not in this map are recorded as OBSERVATION.
+_SPAN_TYPE_TO_EVENT: dict[str, EventType] = {
+    'agent': EventType.AGENT_STEP,
+    'generation': EventType.LLM_RESPONSE,
+    'function': EventType.TOOL_RESULT,
+    'tool': EventType.TOOL_RESULT,
+    'handoff': EventType.HANDOFF,
+    'guardrail': EventType.GUARDRAIL,
+    'response': EventType.LLM_RESPONSE,
+}
+
+
+def _span_attr(span: Any, *names: str) -> Any:
+    """Read the first non-None attribute from `span` (or `span.span_data` if
+    the SDK wraps its payload there).
+    """
+    holders = [span, getattr(span, 'span_data', None)]
+    for holder in holders:
+        if holder is None:
+            continue
+        for name in names:
+            val = getattr(holder, name, None)
+            if val is not None:
+                return val
+    return None
+
+
+class OpenAIAgentsBridge:
+    """Bridge ``agents.tracing`` spans into an AgentDebug trajectory.
+
+    Both a context manager and a plain object with attach/detach. Holds the
+    registered ``TracingProcessor`` so the SDK doesn't GC it mid-session.
+    """
+
+    framework = 'openai-agents'
+
+    def __init__(
+        self,
+        debugger: AgentDebug,
+        trajectory: AgentTrajectory,
+    ) -> None:
+        self.debugger = debugger
+        self.trajectory = trajectory
+        self._processor: Optional[Any] = None
+        self._attached = False
+
+    def attach(self) -> 'OpenAIAgentsBridge':
+        if self._attached:
+            return self
+        tracing = _import_agents_tracing()
+        base_cls = getattr(tracing, 'TracingProcessor', None)
+        if base_cls is None:
+            raise RuntimeError(
+                'agents.tracing.TracingProcessor not found; the installed '
+                '`openai-agents` version may be incompatible.'
+            )
+        bridge = self
+
+        class _Processor(base_cls):  # type: ignore[misc, valid-type]
+            def on_trace_start(self_, trace_obj: Any) -> None:
+                pass
+
+            def on_trace_end(self_, trace_obj: Any) -> None:
+                pass
+
+            def on_span_start(self_, span: Any) -> None:
+                pass
+
+            def on_span_end(self_, span: Any) -> None:
+                bridge._record_span(span)
+
+            def shutdown(self_) -> None:
+                pass
+
+            def force_flush(self_) -> None:
+                pass
+
+        self._processor = _Processor()
+        add = getattr(tracing, 'add_trace_processor', None)
+        if not callable(add):
+            raise RuntimeError(
+                'agents.tracing.add_trace_processor not found; the installed '
+                '`openai-agents` version may be incompatible.'
+            )
+        add(self._processor)
+        self._attached = True
+        return self
+
+    def detach(self) -> None:
+        # The SDK does not expose a clean unsubscribe in current releases.
+        # Dropping the strong reference + having the processor become a no-op
+        # is the safest available approach.
+        self._processor = None
+        self._attached = False
+
+    # Context-manager sugar
+    def __enter__(self) -> 'OpenAIAgentsBridge':
+        return self.attach()
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> Literal[False]:
+        self.detach()
+        return False
+
+    def _record_span(self, span: Any) -> None:
+        try:
+            span_type = str(_span_attr(span, 'span_type', 'type') or 'unknown')
+            event_type = _SPAN_TYPE_TO_EVENT.get(span_type, EventType.OBSERVATION)
+            error = _span_attr(span, 'error')
+            agent_name = (
+                _span_attr(span, 'agent_name', 'name', 'function_name')
+                or span_type
+            )
+            self.debugger.record_event(
+                self.trajectory,
+                event_type=event_type,
+                agent_name=str(agent_name),
+                module=self._module_for(event_type),
+                input=_summarize(_span_attr(span, 'input', 'arguments', 'prompt')),
+                output=_summarize(
+                    _span_attr(span, 'output', 'response', 'result',
+                               'completion')
+                ),
+                error=str(error)[:500] if error else None,
+                openai_agents_span_type=span_type,
+                openai_agents_span_id=str(_span_attr(span, 'span_id') or ''),
+            )
+        except Exception as exc:  # pragma: no cover - defensive
+            LOG.warning('OpenAIAgentsBridge failed to record span: %s', exc)
+
+    @staticmethod
+    def _module_for(event_type: EventType) -> str:
+        # Pull from agentdebug.taxonomy module families: planning/action/etc.
+        if event_type in {EventType.TOOL_CALL, EventType.TOOL_RESULT}:
+            return 'action'
+        if event_type in {EventType.HANDOFF, EventType.GUARDRAIL}:
+            return 'multiagent'
+        if event_type in {EventType.LLM_CALL, EventType.LLM_RESPONSE}:
+            return 'planning'
+        return 'planning'
+
+
+def _summarize(value: Any) -> Any:
+    if value is None:
+        return None
+    text = str(value)
+    return text[:1000] if len(text) > 1000 else text
+
+
+class OpenAIAgentsAdapter:
+    """Structural :class:`FrameworkAdapter` for the doctor."""
+
+    framework = 'openai-agents'
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:  # noqa: D401
+        try:
+            _import_agents_tracing()
+        except ImportError as exc:
+            return AdapterStatus(
+                framework=self.framework,
+                implemented=False,
+                notes=str(exc),
+            )
+        return AdapterStatus(
+            framework=self.framework,
+            implemented=True,
+            notes=(
+                'Create a trajectory, then use '
+                '`with OpenAIAgentsBridge(debugger, trajectory): Runner.run_sync(...)` '
+                'to record every Agent/Runner/Function/Handoff/Guardrail span '
+                'into AgentDebug.'
+            ),
+        )
+
+
+_: FrameworkAdapter = OpenAIAgentsAdapter()  # static structural check
+
+
+__all__ = ['OpenAIAgentsAdapter', 'OpenAIAgentsBridge']

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/src/agentdebug/cli.py

@@ -453,6 +453,12 @@ def _cmd_doctor() -> int:
         statuses.append(CrewAIAdapter().instrument(_dummy_debugger()))
     except Exception as exc:  # pragma: no cover - defensive
         statuses.append(_status('crewai', False, str(exc)))
+    try:
+        from agentdebug.adapters.openai_agents import OpenAIAgentsAdapter
+
+        statuses.append(OpenAIAgentsAdapter().instrument(_dummy_debugger()))
+    except Exception as exc:  # pragma: no cover - defensive
+        statuses.append(_status('openai-agents', False, str(exc)))
     try:
         from agentdebug.adapters.otel import OTelExportAdapter
 

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/src/agentdebug/detectors.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass
-from typing import List, Optional, Protocol
+from typing import Any, List, Optional, Protocol
 
 from agentdebug.models import (
     AgentEvent,
@@ -273,12 +273,106 @@ def _suggestion(mode: FailureMode) -> Optional[str]:
     return None
 
 
+class TopicDriftDetector:
+    """Embedding-based anomaly detector for goal drift.
+
+    Embed the trajectory's goal once; embed each user-facing event payload
+    (LLM_RESPONSE / PLAN / OBSERVATION outputs); flag any step whose cosine
+    similarity with the goal drops below ``threshold``.
+
+    Maps to ``FM-2.3 task_derailment`` (MAST) / ``planning.inefficient_plan``.
+    Closes the anomaly family from doc 06 alongside the existing
+    RepeatedToolCallDetector / RepeatedStateDetector.
+
+    Skipped silently if the embedding client raises or returns no vectors —
+    the rest of the detector pipeline is unaffected.
+    """
+
+    id = 'topic_drift'
+
+    def __init__(
+        self,
+        embedding_client: Any,
+        *,
+        threshold: float = 0.35,
+        max_events: int = 60,
+    ) -> None:
+        # embedding_client is duck-typed to EmbeddingClient to avoid an
+        # import cycle (detectors.py is imported from agentdebug/__init__.py).
+        self.embedding_client = embedding_client
+        self.threshold = threshold
+        self.max_events = max_events
+
+    def detect(self, trajectory: AgentTrajectory) -> List[FailureFinding]:
+        if not trajectory.goal:
+            return []
+        contextful = [
+            e for e in trajectory.events
+            if e.event_type in {
+                EventType.LLM_RESPONSE, EventType.PLAN, EventType.OBSERVATION,
+                EventType.LLM_RESPONSE.value, EventType.PLAN.value,
+                EventType.OBSERVATION.value,
+            }
+            and e.output is not None and str(e.output).strip()
+        ]
+        if not contextful:
+            return []
+        contextful = contextful[-self.max_events:]
+        texts = [trajectory.goal] + [str(e.output)[:1000] for e in contextful]
+        try:
+            vectors = self.embedding_client.embed(texts)
+        except Exception as exc:  # pragma: no cover - defensive
+            LOG.warning('topic_drift detector embed() failed: %s', exc)
+            return []
+        if not vectors or len(vectors) != len(texts):
+            return []
+        goal_vec = vectors[0]
+        findings: List[FailureFinding] = []
+        mode = SEED_FAILURE_MODES['planning.inefficient_plan']
+        for evt, evt_vec in zip(contextful, vectors[1:]):
+            sim = _cosine(goal_vec, evt_vec)
+            if sim >= self.threshold:
+                continue
+            findings.append(FailureFinding(
+                finding_id=new_id('finding'),
+                failure_mode=mode,
+                event_id=evt.event_id,
+                agent_name=evt.agent_name,
+                step_index=evt.step_index,
+                # Confidence proportional to how far below threshold we drifted.
+                confidence=min(0.95, 0.4 + (self.threshold - sim)),
+                evidence=[
+                    f'goal/output cosine={sim:.3f} < threshold={self.threshold:.2f}',
+                ],
+                suggestion=_suggestion(mode),
+                metadata={
+                    'source': self.id,
+                    'cosine_to_goal': round(sim, 4),
+                    'threshold': self.threshold,
+                },
+            ))
+        return findings
+
+
+def _cosine(a: List[float], b: List[float]) -> float:
+    import math
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)
+
+
 __all__ = [
     'Detector',
     'DetectorConfig',
     'RepeatedStateDetector',
     'RepeatedToolCallDetector',
     'StepCountLimitDetector',
+    'TopicDriftDetector',
     'default_detectors',
     'run_detectors',
 ]

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/src/agentdebug/llm.py

@@ -44,6 +44,25 @@ class LLMClient(Protocol):
         ...
 
 
+class EmbeddingClient(Protocol):
+    """Subprotocol for clients that also expose ``/v1/embeddings``.
+
+    Kept separate from :class:`LLMClient` so detectors can declare a
+    narrower dependency and tests can stub embeddings without faking
+    a chat client.
+    """
+
+    embedding_model: str
+
+    def embed(
+        self,
+        texts: List[str],
+        *,
+        timeout: float = 60.0,
+    ) -> List[List[float]]:
+        ...
+
+
 class OpenAICompatClient:
     """OpenAI-compatible chat completions client.
 
@@ -63,12 +82,16 @@ class OpenAICompatClient:
         base_url: str,
         api_key: str,
         model: str,
+        embedding_model: str = 'text-embedding-3-small',
         default_max_tokens: int = 2048,
         timeout: float = 60.0,
     ) -> None:
         self.base_url = base_url.rstrip('/')
         self.api_key = api_key
         self.model = model
+        # Embeddings hit a separate endpoint with a separate model id; default
+        # to OpenAI's small embedding model since the gateway is OpenAI-compat.
+        self.embedding_model = embedding_model
         self.default_max_tokens = default_max_tokens
         self.timeout = timeout
 
@@ -132,6 +155,40 @@ class OpenAICompatClient:
         return CompletionResult(text=text, raw=data)
 
 
+    def embed(
+        self,
+        texts: List[str],
+        *,
+        timeout: Optional[float] = None,
+    ) -> List[List[float]]:
+        """OpenAI-compatible ``/v1/embeddings`` POST.
+
+        Returns a list of vectors (one per input text) in the same order.
+        Empty ``texts`` short-circuits to ``[]`` to save a network round-trip.
+        """
+        if not texts:
+            return []
+        url = f'{self.base_url}/embeddings'
+        headers = {
+            'Authorization': f'Bearer {self.api_key}',
+            'Content-Type': 'application/json',
+        }
+        body = {'model': self.embedding_model, 'input': list(texts)}
+        resp = httpx.post(
+            url, headers=headers, json=body, timeout=timeout or self.timeout
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        rows = data.get('data') or []
+        out: List[List[float]] = []
+        for row in rows:
+            vec = row.get('embedding')
+            if not isinstance(vec, list):
+                continue
+            out.append([float(v) for v in vec])
+        return out
+
+
 def extract_json_block(text: str) -> Optional[Dict[str, Any]]:
     """Extract the first top-level JSON object from a possibly-fenced response."""
     if not text:

{agentdebugx-0.2.10 → agentdebugx-0.2.12}/src/agentdebug/recovery.py

@@ -13,9 +13,10 @@ artifacts to be surfaced (CLI/UI/PR comment) or fed back into the next run.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import List, Optional, Protocol, Tuple
+from typing import Any, Callable, Dict, List, Optional, Protocol, Tuple
 
 from agentdebug.models import (
+    AgentEvent,
     AgentTrajectory,
     DiagnosticReport,
     FailureFinding,
@@ -583,13 +584,198 @@ class AutoManualRules:
         return rule
 
 
+@dataclass
+class CompensationSpec:
+    """Pairs a tool name with the function that undoes its side effect.
+
+    The compensation receives the recorded TOOL_CALL input + TOOL_RESULT
+    output and returns a short human-readable summary of what was
+    rolled back. The function is the user's responsibility — AgentDebug
+    only orchestrates the order and provenance.
+    """
+
+    tool_name: str
+    description: str
+    compensate: Callable[[Any, Any], str]
+
+
+class Compensator:
+    """Registry mapping tool_name → :class:`CompensationSpec`.
+
+    Users register compensations once per tool the agent might call with a
+    side effect (email send, DB write, API POST, file create). The Saga
+    recoverer looks up compensations by the agent_name on a TOOL_CALL /
+    TOOL_RESULT pair.
+    """
+
+    def __init__(self) -> None:
+        self._specs: dict[str, CompensationSpec] = {}
+
+    def register(
+        self,
+        tool_name: str,
+        compensate: Callable[[Any, Any], str],
+        *,
+        description: str = '',
+    ) -> CompensationSpec:
+        spec = CompensationSpec(
+            tool_name=tool_name,
+            description=description or f'compensation for {tool_name}',
+            compensate=compensate,
+        )
+        self._specs[tool_name] = spec
+        return spec
+
+    def get(self, tool_name: str) -> Optional[CompensationSpec]:
+        return self._specs.get(tool_name)
+
+    def registered_tools(self) -> list[str]:
+        return sorted(self._specs.keys())
+
+
+@dataclass
+class _ToolPair:
+    """A matched TOOL_CALL / TOOL_RESULT pair from a trajectory."""
+
+    call_event_id: str
+    result_event_id: str
+    tool_name: str
+    step_index: Optional[int]
+    input: Any
+    output: Any
+    error: Optional[str]
+
+
+def _pair_tool_calls(trajectory: AgentTrajectory) -> List[_ToolPair]:
+    """Walk the trajectory and emit (call, result) pairs by agent_name +
+    proximity. Calls without a following result are dropped (the tool never
+    completed, so there's nothing to compensate)."""
+    pairs: List[_ToolPair] = []
+    pending: Dict[str, AgentEvent] = {}
+    for evt in trajectory.events:
+        et = getattr(evt.event_type, 'value', evt.event_type)
+        if et == 'tool.call':
+            pending[evt.agent_name] = evt
+            continue
+        if et == 'tool.result' and evt.agent_name in pending:
+            call = pending.pop(evt.agent_name)
+            pairs.append(_ToolPair(
+                call_event_id=call.event_id,
+                result_event_id=evt.event_id,
+                tool_name=evt.agent_name,
+                step_index=evt.step_index or call.step_index,
+                input=call.input,
+                output=evt.output,
+                error=evt.error,
+            ))
+    return pairs
+
+
+class SagaRollback:
+    """SagaLLM-style compensating-action layer (arXiv:2503.11951).
+
+    For every successful TOOL_CALL/TOOL_RESULT pair in the trajectory whose
+    tool has a registered compensation, emit a :class:`FixProposal`. Tool
+    results with an error are skipped — there's nothing to undo.
+
+    Proposals are returned in REVERSE EXECUTION ORDER so applying them
+    walks the side effects back to a clean state. Each ``apply()`` invokes
+    the user-provided ``compensate(input, output)`` and returns the
+    function's summary string.
+
+    Unlike the suggest-only Reflexion / CRITIC / Self-Refine / AutoManual
+    recoverers, ``apply()`` here HAS REAL SIDE EFFECTS — it runs the
+    user's compensation code. Marked ``requires_human_approval=True`` by
+    default so the UI surfaces every rollback for confirmation.
+    """
+
+    id = 'saga_rollback'
+
+    def __init__(
+        self,
+        compensator: Compensator,
+        *,
+        require_approval: bool = True,
+    ) -> None:
+        self.compensator = compensator
+        self.require_approval = require_approval
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        # Recovery suggestions are independent of the report — saga always
+        # looks at the trajectory's actual side-effect surface.
+        del report
+        pairs = _pair_tool_calls(trajectory)
+        # Reverse order so consumers can apply in sequence.
+        proposals: List[FixProposal] = []
+        for pair in reversed(pairs):
+            if pair.error:
+                continue  # tool failed; no side effect to compensate
+            spec = self.compensator.get(pair.tool_name)
+            if spec is None:
+                continue  # no registered compensation; can't auto-rollback
+            proposals.append(FixProposal(
+                proposal_id=new_id('fix'),
+                recoverer_id=self.id,
+                target_event_id=pair.result_event_id,
+                summary=(
+                    f'Compensate {pair.tool_name} call '
+                    f'at step {pair.step_index}'
+                ),
+                rationale=(
+                    f'SagaRollback (arXiv:2503.11951): undo the recorded '
+                    f'side effect of {pair.tool_name}. '
+                    f'Compensation: {spec.description}'
+                ),
+                confidence=0.85,
+                suggestion_text=(
+                    f'apply() will call the registered compensation for '
+                    f'`{pair.tool_name}` with the recorded input/output, '
+                    f'reversing the side effect.'
+                ),
+                side_effects=[f'tool.compensate:{pair.tool_name}'],
+                requires_human_approval=self.require_approval,
+            ))
+        return proposals
+
+    def apply(self, proposal: FixProposal, *, trajectory: AgentTrajectory) -> str:
+        """Run the registered compensation. Returns the user's summary string.
+
+        ``trajectory`` is required so apply can recover the recorded
+        input/output from the target event without the caller having to
+        carry them through.
+        """
+        pairs_by_result = {
+            p.result_event_id: p for p in _pair_tool_calls(trajectory)
+        }
+        pair = pairs_by_result.get(proposal.target_event_id or '')
+        if pair is None:
+            raise ValueError(
+                f'proposal target_event_id={proposal.target_event_id!r} not '
+                f'found among tool-result events in the trajectory'
+            )
+        spec = self.compensator.get(pair.tool_name)
+        if spec is None:
+            raise ValueError(
+                f'no registered compensation for tool {pair.tool_name!r}; '
+                f'register it on the Compensator before applying'
+            )
+        return spec.compensate(pair.input, pair.output)
+
+
 __all__ = [
     'AutoManualRules',
+    'CompensationSpec',
+    'Compensator',
     'CriticRecoverer',
     'DEFAULT_VERIFIERS',
     'FixProposal',
     'Recoverer',
     'ReflexionSuggestion',
+    'SagaRollback',
     'SelfRefineLoop',
     'VerifierSpec',
 ]