agentdebugx 0.2.0__tar.gz → 0.2.1__tar.gz

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdebugx
-Version: 0.2.0
+Version: 0.2.1
 Summary: Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`.
 License: MIT
 License-File: LICENSE
@@ -187,6 +187,10 @@ agentdebug serve --store-sqlite .agentdebug/errors.sqlite
 # DeepDebug — iterative multi-turn analysis (plan -> hypothesize -> verify -> refine)
 agentdebug deep <trajectory.json>
 
+# Render the cascade as a Python-traceback (root cause first, manifested failure last)
+agentdebug deep <trajectory.json> --traceback
+agentdebug analyze <trajectory.json> --traceback   # works without an LLM too
+
 # Error Hub: package + push a trace to a Git remote or HF dataset
 agentdebug hub push <trace_id> \
     --to git:git@github.com:your-org/agentdebug-bundles.git#bundles \

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/README.md

@@ -147,6 +147,10 @@ agentdebug serve --store-sqlite .agentdebug/errors.sqlite
 # DeepDebug — iterative multi-turn analysis (plan -> hypothesize -> verify -> refine)
 agentdebug deep <trajectory.json>
 
+# Render the cascade as a Python-traceback (root cause first, manifested failure last)
+agentdebug deep <trajectory.json> --traceback
+agentdebug analyze <trajectory.json> --traceback   # works without an LLM too
+
 # Error Hub: package + push a trace to a Git remote or HF dataset
 agentdebug hub push <trace_id> \
     --to git:git@github.com:your-org/agentdebug-bundles.git#bundles \

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/docs/20_deep_debug.md

@@ -115,6 +115,52 @@ rounds        : plan (4.6s) hypothesize (11.0s)
 The single-pass `LLMJudgeAnalyzer` on the same trace returned only the first
 finding. DeepDebug recovered the full cascade and selected the upstream cause.
 
+## 6.1 AgentTraceback — Python-traceback-style cascade view
+
+Once DeepDebug has populated `finding.metadata['cascading_from_event_id']`,
+`agentdebug.traceback.format_traceback(report, trajectory)` renders the
+cascade in a layout that mirrors Python's `Traceback (most recent call last)`
+— root cause first, manifested failure last, with arrows between hops:
+
+```text
+AgentTraceback (root cause first, manifested failure last):
+    trace_id=trace_…  framework=live-cascade-demo  goal='Find latest paper, summarize, then email …'
+
+      File "root cause", in trajectory
+        Step 3  agent=search  mode=action.parameter_error  confidence=1.00
+          module=action
+          error>  JSON schema validation failed: missing parameter query
+          evidence:
+            - args={}
+          suggested: Validate parameters against tool schemas before execution.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 4  agent=planner  mode=verification.premature_stop  confidence=1.00
+          output> Final answer: AgentDebug is a popular paper.
+    ↓ cascaded to
+      File "cascade depth 1", in trajectory
+        Step 4  agent=planner  mode=memory.hallucination  confidence=0.95
+          output> Final answer: AgentDebug is a popular paper.
+
+AgentFailure[memory.hallucination]: The search agent failed to provide the
+required 'query' parameter in its tool call, leading to a tool error. The
+planner then hallucinated a generic fact about the paper and prematurely
+terminated the task without completing the summary or email steps.
+```
+
+CLI:
+
+```bash
+agentdebug deep <trajectory.json> --traceback         # render to stdout
+agentdebug analyze <trajectory.json> --traceback      # works for rule analyzer too
+agentdebug judge <traj|trace_id> --attribute --traceback
+```
+
+When DeepDebug isn't available (heuristic analyzer or single-pass judge),
+the renderer falls back to **step-index ordering** — the earliest finding
+becomes the root and later findings cascade from it. This means
+`--traceback` works on any analyzer in the pipeline, not just DeepDebug.
+
 ## 7. Failure modes
 
 - **Cost blowout** — if `max_hypotheses_to_verify` is high and verify is

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentdebugx"
-version = "0.2.0"
+version = "0.2.1"
 description = "Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`."
 authors = ["ULab @ UIUC <ulab@illinois.edu>"]
 license = "MIT"

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/src/agentdebug/__init__.py

@@ -29,6 +29,7 @@ from agentdebug.models import (
 )
 from agentdebug.recorder import AgentDebug, TraceSession
 from agentdebug.recovery import FixProposal, Recoverer, ReflexionSuggestion
+from agentdebug.traceback import CascadeFrame, build_cascade, format_traceback
 from agentdebug.storage import JsonlTraceStore, SQLiteTraceStore
 from agentdebug.taxonomy import SEED_FAILURE_MODES, get_failure_mode
 
@@ -42,6 +43,9 @@ __all__ = [
     'Attributor',
     'Blame',
     'BusEvent',
+    'CascadeFrame',
+    'build_cascade',
+    'format_traceback',
     'DEFAULT_BUS',
     'DiagnosticReport',
     'EventBus',
@@ -62,4 +66,4 @@ __all__ = [
     'get_failure_mode',
 ]
 
-__version__ = '0.2.0'
+__version__ = '0.2.1'

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/src/agentdebug/cli.py

@@ -36,6 +36,15 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         action='store_true',
         help='Also emit Reflexion-style retry suggestions for each finding',
     )
+    p_analyze.add_argument(
+        '--traceback',
+        action='store_true',
+        help='Render a Python-traceback-style cascade view instead of JSON',
+    )
+    p_analyze.add_argument(
+        '--no-color', action='store_true',
+        help='Disable ANSI colors in --traceback output (default: auto)',
+    )
 
     p_list = sub.add_parser('list', help='List trace IDs in a store')
     _add_store_args(p_list)
@@ -131,6 +140,11 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     p_deep.add_argument('--base-url', dest='base_url')
     p_deep.add_argument('--api-key', dest='api_key')
     p_deep.add_argument('--out', help='Optional output path for the report JSON')
+    p_deep.add_argument(
+        '--traceback', action='store_true',
+        help='Render a Python-traceback-style cascade view to stdout',
+    )
+    p_deep.add_argument('--no-color', action='store_true')
 
     args = parser.parse_args(argv)
     if args.command == 'analyze':
@@ -161,6 +175,14 @@ def _cmd_analyze(args: argparse.Namespace) -> int:
     trajectory_path = Path(args.trajectory)
     trajectory = trajectory_from_json(trajectory_path.read_text(encoding='utf-8'))
     report = HeuristicAnalyzer().analyze(trajectory)
+    if args.traceback:
+        from agentdebug.traceback import format_traceback
+
+        text = format_traceback(
+            report, trajectory, use_color=not args.no_color and sys.stdout.isatty()
+        )
+        _emit(text, args.out)
+        return 0
     rendered = model_to_json(report, indent=2)
     if args.suggest:
         proposals = ReflexionSuggestion().suggest(trajectory, report)
@@ -232,6 +254,17 @@ def _cmd_judge(args: argparse.Namespace) -> int:
     if args.attribute:
         blame = AllAtOnceAttributor(llm=llm).attribute(trajectory, report.findings)
         rendered = _augment_with_blame(rendered, blame)
+    if args.traceback:
+        from agentdebug.traceback import format_traceback
+
+        rendered = (
+            rendered
+            + '\n\n# === AgentTraceback ===\n'
+            + format_traceback(
+                report, trajectory,
+                use_color=not args.no_color and sys.stdout.isatty(),
+            )
+        )
     _emit(rendered, args.out)
     return 0
 
@@ -394,6 +427,15 @@ def _cmd_deep(args: argparse.Namespace) -> int:
     for r in result.rounds:
         print(f'  {r.name:>20} {r.duration_ms:>6} ms', file=sys.stderr)
     _emit(out_text, args.out)
+    if args.traceback:
+        from agentdebug.traceback import format_traceback
+
+        text = format_traceback(
+            result.report, trajectory,
+            use_color=not args.no_color and sys.stdout.isatty(),
+        )
+        print()
+        print(text)
     return 0
 
 

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/src/agentdebug/deep.py

@@ -200,6 +200,11 @@ class DeepDebugAnalyzer:
 
     def analyze(self, trajectory: AgentTrajectory) -> DeepDebugResult:
         rounds: List[DeepDebugRound] = []
+        # Per-event-id lookup of the most recent verified cascade predecessor;
+        # populated by _verify and consumed in _compose_report so the cascade
+        # info survives the verify -> refine handoff even when the refine LLM
+        # doesn't echo it back verbatim.
+        self._cascade_lookup: Dict[str, str] = {}
 
         plan = self._plan(trajectory, rounds)
         raw_focus = plan.get('focus_event_ids') or []
@@ -309,6 +314,10 @@ class DeepDebugAnalyzer:
         hypothesis.cascading_from_event_id = self._opt_str(
             parsed.get('cascading_from_event_id')
         )
+        if hypothesis.event_id and hypothesis.cascading_from_event_id:
+            self._cascade_lookup[hypothesis.event_id] = (
+                hypothesis.cascading_from_event_id
+            )
 
     def _refine(
         self,
@@ -427,16 +436,28 @@ class DeepDebugAnalyzer:
             mode = SEED_FAILURE_MODES.get(mid)
             if mode is None:
                 continue
+            event_id = self._opt_str(raw.get('event_id'))
+            # Carry the cascade predecessor we extracted in verify so the
+            # AgentTraceback renderer can chain findings.
+            cascade_from: Optional[str] = None
+            if event_id is not None:
+                cascade_from = self._cascade_lookup.get(event_id)
+            cascade_from_raw = self._opt_str(raw.get('cascading_from_event_id'))
+            if cascade_from_raw:
+                cascade_from = cascade_from_raw
+            finding_metadata: Dict[str, Any] = {'source': 'deep_debug'}
+            if cascade_from:
+                finding_metadata['cascading_from_event_id'] = cascade_from
             findings.append(FailureFinding(
                 finding_id=new_id('finding'),
                 failure_mode=mode,
-                event_id=self._opt_str(raw.get('event_id')),
+                event_id=event_id,
                 agent_name=self._opt_str(raw.get('agent_name')),
                 step_index=self._opt_int(raw.get('step_index')),
                 confidence=self._opt_float(raw.get('confidence'), 0.5),
                 evidence=self._str_list(raw.get('evidence')),
                 suggestion=self._suggestion(mode),
-                metadata={'source': 'deep_debug'},
+                metadata=finding_metadata,
             ))
         root = parsed.get('root_cause') or {}
         report = DiagnosticReport(

agentdebugx-0.2.1/src/agentdebug/traceback.py

@@ -0,0 +1,302 @@
+"""Python-traceback-style rendering of cascading agent failures.
+
+A diagnostic report contains a *set* of findings; what users actually want is
+a *chain* that shows how a single root cause cascaded through later steps,
+ending at the manifested failure — exactly the way a Python traceback walks
+from the outermost frame to the raised exception.
+
+Two inputs feed the chain:
+
+* DeepDebug findings populate ``finding.metadata['cascading_from_event_id']``
+  with the predecessor's event ID, so the cascade is explicit and verified.
+* Heuristic / single-shot LLM judges don't compute a cascade, so we fall
+  back to **step-index ordering** with the earliest finding as the root.
+
+Public API::
+
+    from agentdebug.traceback import format_traceback
+    print(format_traceback(report, trajectory))
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from agentdebug.models import AgentEvent, AgentTrajectory, DiagnosticReport, FailureFinding
+
+
+@dataclass
+class CascadeFrame:
+    """One frame in the cascade — analogous to one Python traceback line."""
+
+    finding: FailureFinding
+    event: Optional[AgentEvent]
+    cascades_from_event_id: Optional[str] = None
+    depth: int = 0  # 0 = root cause; deepest = manifested failure
+    children_event_ids: List[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Cascade construction
+# ---------------------------------------------------------------------------
+
+def build_cascade(
+    report: DiagnosticReport,
+    trajectory: Optional[AgentTrajectory] = None,
+) -> List[CascadeFrame]:
+    """Build an ordered chain of frames (root → manifested) from a report.
+
+    Uses ``finding.metadata['cascading_from_event_id']`` when present;
+    otherwise falls back to step-index ordering.
+    """
+    if not report.findings:
+        return []
+
+    events_by_id: Dict[str, AgentEvent] = {}
+    if trajectory is not None:
+        for evt in trajectory.events:
+            events_by_id[evt.event_id] = evt
+
+    # Group findings by event_id so duplicates collapse cleanly.
+    by_event: Dict[str, List[FailureFinding]] = {}
+    orphans: List[FailureFinding] = []
+    for f in report.findings:
+        if f.event_id:
+            by_event.setdefault(f.event_id, []).append(f)
+        else:
+            orphans.append(f)
+
+    # Extract predecessor links.
+    predecessor: Dict[str, Optional[str]] = {}
+    for event_id, findings in by_event.items():
+        # Best predecessor wins (any non-null among the findings on this event).
+        cand: Optional[str] = None
+        for f in findings:
+            meta_value = f.metadata.get('cascading_from_event_id')
+            if isinstance(meta_value, str) and meta_value:
+                cand = meta_value
+                break
+        predecessor[event_id] = cand
+
+    # Determine root: prefer report.root_cause_event_id, else the finding with
+    # the smallest step_index (None pushed to the end), then highest confidence.
+    root_event_id: Optional[str] = report.root_cause_event_id
+    if root_event_id not in by_event:
+        ordered = sorted(
+            by_event.items(),
+            key=lambda kv: (
+                _min_step(kv[1]) is None,
+                _min_step(kv[1]) if _min_step(kv[1]) is not None else 10**9,
+                -max(f.confidence for f in kv[1]),
+            ),
+        )
+        root_event_id = ordered[0][0] if ordered else None
+
+    chain_event_ids: List[str] = []
+    if root_event_id is not None:
+        # Walk descendants from root using the predecessor map (reverse it).
+        descendants: Dict[str, List[str]] = {}
+        for child, parent in predecessor.items():
+            if parent and parent in by_event:
+                descendants.setdefault(parent, []).append(child)
+
+        visited: set[str] = set()
+
+        def dfs(node: str) -> None:
+            if node in visited:
+                return
+            visited.add(node)
+            chain_event_ids.append(node)
+            # Sort children by step_index so we walk forward in time.
+            children = sorted(
+                descendants.get(node, []),
+                key=lambda eid: _min_step(by_event[eid]) or 10**9,
+            )
+            for child in children:
+                dfs(child)
+
+        dfs(root_event_id)
+
+        # Any disconnected findings: append by step order at the end.
+        leftover = [
+            eid for eid in by_event
+            if eid not in visited
+        ]
+        leftover.sort(
+            key=lambda eid: _min_step(by_event[eid]) or 10**9
+        )
+        chain_event_ids.extend(leftover)
+    else:
+        # No structural cascade info — fall back to step order.
+        chain_event_ids = sorted(
+            by_event.keys(),
+            key=lambda eid: _min_step(by_event[eid]) or 10**9,
+        )
+
+    frames: List[CascadeFrame] = []
+    for depth, event_id in enumerate(chain_event_ids):
+        # If multiple findings on this event, emit one frame per finding but
+        # group them — earliest-confidence-tiebreak first.
+        ranked = sorted(
+            by_event[event_id],
+            key=lambda f: -f.confidence,
+        )
+        for f in ranked:
+            frames.append(CascadeFrame(
+                finding=f,
+                event=events_by_id.get(event_id),
+                cascades_from_event_id=predecessor.get(event_id),
+                depth=depth,
+            ))
+    # Orphan findings (no event_id) appended at the end.
+    for f in orphans:
+        frames.append(CascadeFrame(
+            finding=f, event=None, cascades_from_event_id=None,
+            depth=len(chain_event_ids),
+        ))
+    return frames
+
+
+# ---------------------------------------------------------------------------
+# Formatting
+# ---------------------------------------------------------------------------
+
+def format_traceback(
+    report: DiagnosticReport,
+    trajectory: Optional[AgentTrajectory] = None,
+    *,
+    use_color: bool = False,
+    indent: str = '    ',
+) -> str:
+    """Render a cascading agent-failure traceback.
+
+    Output mirrors Python's traceback shape: a header, frames ordered
+    *root → manifested*, then a final summary line that names the failure.
+    """
+    frames = build_cascade(report, trajectory)
+    if not frames:
+        return _wrap_color(
+            'AgentTraceback: no findings recorded.',
+            'muted',
+            use_color,
+        )
+
+    lines: List[str] = []
+    header = 'AgentTraceback (root cause first, manifested failure last):'
+    lines.append(_wrap_color(header, 'header', use_color))
+    if trajectory is not None:
+        meta = []
+        if trajectory.trace_id:
+            meta.append(f'trace_id={trajectory.trace_id}')
+        if trajectory.framework:
+            meta.append(f'framework={trajectory.framework}')
+        if trajectory.goal:
+            meta.append(f'goal={trajectory.goal!r}')
+        if meta:
+            lines.append(indent + _wrap_color('  '.join(meta), 'meta', use_color))
+        lines.append('')
+
+    for idx, frame in enumerate(frames):
+        lines.extend(_format_frame(frame, indent=indent, use_color=use_color))
+        if idx < len(frames) - 1:
+            lines.append(indent + _wrap_color('↓ cascaded to', 'arrow', use_color))
+
+    # Tail summary — analogue to "TypeError: ..." in Python tracebacks.
+    final = frames[-1].finding
+    summary = report.summary or final.failure_mode.name
+    tail = (
+        f'AgentFailure[{final.failure_mode.mode_id}]: '
+        f'{summary}'
+    )
+    lines.append('')
+    lines.append(_wrap_color(tail, 'failure', use_color))
+    return '\n'.join(lines)
+
+
+def _format_frame(
+    frame: CascadeFrame, *, indent: str, use_color: bool
+) -> List[str]:
+    f = frame.finding
+    event = frame.event
+    role = 'root cause' if frame.depth == 0 else f'cascade depth {frame.depth}'
+    header_parts = [
+        f'Step {f.step_index if f.step_index is not None else "?"}',
+        f'agent={f.agent_name or "?"}',
+        f'mode={f.failure_mode.mode_id}',
+        f'confidence={f.confidence:.2f}',
+    ]
+    header = f'  File "{role}", in trajectory'
+    sub = f'    {"  ".join(header_parts)}'
+
+    lines: List[str] = [
+        indent + _wrap_color(header, 'frame', use_color),
+        indent + _wrap_color(sub, 'frame-meta', use_color),
+    ]
+    if event is not None:
+        if event.module:
+            lines.append(indent + f'      module={event.module}')
+        if event.event_id:
+            lines.append(indent + f'      event_id={event.event_id}')
+        if event.input is not None and str(event.input).strip():
+            lines.append(indent + f'      input>  {_truncate(event.input)}')
+        if event.output is not None and str(event.output).strip():
+            lines.append(indent + f'      output> {_truncate(event.output)}')
+        if event.error:
+            lines.append(
+                indent
+                + _wrap_color(f'      error>  {_truncate(event.error)}', 'error', use_color)
+            )
+    if f.evidence:
+        lines.append(indent + '      evidence:')
+        for ev in f.evidence:
+            lines.append(indent + f'        - {_truncate(ev, 220)}')
+    if f.suggestion:
+        lines.append(
+            indent
+            + _wrap_color(f'      suggested: {_truncate(f.suggestion, 220)}', 'suggestion', use_color)
+        )
+    return lines
+
+
+def _truncate(value: object, max_chars: int = 160) -> str:
+    text = '' if value is None else str(value)
+    text = text.replace('\n', ' ')
+    if len(text) > max_chars:
+        return text[:max_chars] + '…'
+    return text
+
+
+def _min_step(findings: List[FailureFinding]) -> Optional[int]:
+    steps = [f.step_index for f in findings if f.step_index is not None]
+    return min(steps) if steps else None
+
+
+# ---------------------------------------------------------------------------
+# Tiny ANSI colorization (no dep)
+# ---------------------------------------------------------------------------
+
+_PALETTE = {
+    'header':     '\033[1;37m',   # bold white
+    'meta':       '\033[2m',      # dim
+    'frame':      '\033[1;36m',   # cyan, bold
+    'frame-meta': '\033[36m',     # cyan
+    'arrow':      '\033[2;33m',   # dim yellow
+    'error':      '\033[31m',     # red
+    'suggestion': '\033[32m',     # green
+    'failure':    '\033[1;31m',   # bold red
+    'muted':      '\033[2m',
+}
+_RESET = '\033[0m'
+
+
+def _wrap_color(text: str, style: str, use_color: bool) -> str:
+    if not use_color:
+        return text
+    code = _PALETTE.get(style)
+    if not code:
+        return text
+    return f'{code}{text}{_RESET}'
+
+
+__all__ = ['CascadeFrame', 'build_cascade', 'format_traceback']

{agentdebugx-0.2.0 → agentdebugx-0.2.1}/src/agentdebug/ui/server.py

@@ -84,7 +84,19 @@ def build_app(store: TraceStore) -> Any:
 
     @app.get('/', response_class=HTMLResponse)
     def index() -> str:
-        return _INDEX_HTML
+        bootstrap: Dict[str, Any] = {'traces': [], 'selected': None}
+        trace_ids = store.list_traces()
+        bootstrap['traces'] = trace_ids
+        if trace_ids:
+            trajectory = store.load_trajectory(trace_ids[0])
+            if trajectory is not None:
+                report = HeuristicAnalyzer().analyze(trajectory)
+                bootstrap['selected'] = {
+                    'trajectory': _to_dict(trajectory),
+                    'report': _to_dict(report),
+                }
+        payload = json.dumps(bootstrap).replace('</', '<\\/')
+        return _INDEX_HTML.replace('__BOOTSTRAP_JSON__', payload)
 
     return app
 
@@ -161,7 +173,7 @@ _INDEX_HTML = """<!doctype html>
   }
   .side-section-title {
     color:var(--muted2); text-transform:uppercase; font-size:11px;
-    font-weight:760; letter-spacing:.08em; margin:8px 0 8px;
+    font-weight:760; letter-spacing:0; margin:8px 0 8px;
   }
   .run-list { list-style:none; padding:0; margin:0; display:flex; flex-direction:column; gap:8px; }
   .run {
@@ -213,13 +225,13 @@ _INDEX_HTML = """<!doctype html>
   }
   .hero-main { padding:18px; }
   .kicker { color:var(--cyan); font-size:11px; text-transform:uppercase;
-    letter-spacing:.12em; font-weight:800; }
+    letter-spacing:0; font-weight:800; }
   h1 { margin:8px 0 8px; font-size:26px; line-height:1.15; letter-spacing:0; }
   .goal { color:var(--muted); font-size:13px; line-height:1.45; max-width:92ch; }
   .meta-line { display:flex; gap:8px; flex-wrap:wrap; margin-top:15px; }
   .stats { display:grid; grid-template-columns:repeat(2, minmax(0,1fr)); gap:10px; padding:12px; }
   .stat { background:var(--panel2); border:1px solid #303434; border-radius:8px; padding:12px; }
-  .stat-label { color:var(--muted2); font-size:11px; text-transform:uppercase; letter-spacing:.08em; }
+  .stat-label { color:var(--muted2); font-size:11px; text-transform:uppercase; letter-spacing:0; }
   .stat-value { margin-top:7px; font-size:22px; line-height:1; font-weight:760; }
   .stat-value.bad { color:var(--rose); }
   .stat-value.warn { color:var(--amber); }
@@ -233,6 +245,16 @@ _INDEX_HTML = """<!doctype html>
   .panel-title { font-size:13px; font-weight:760; }
   .panel-body { padding:14px; }
   .timeline { display:flex; flex-direction:column; gap:10px; }
+  .trace-legend {
+    display:grid; grid-template-columns:minmax(0,1fr) minmax(0,1fr); gap:10px;
+    margin-bottom:10px;
+  }
+  .legend-cell {
+    border:1px solid #303434; background:#171919; border-radius:8px; padding:10px;
+    min-width:0;
+  }
+  .legend-label { color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:0; }
+  .legend-title { margin-top:4px; font-size:13px; font-weight:760; }
   .event {
     display:grid; grid-template-columns:58px minmax(0,1fr); gap:12px;
     border:1px solid #2c302f; border-radius:8px; background:#1a1c1c; padding:12px;
@@ -247,9 +269,31 @@ _INDEX_HTML = """<!doctype html>
   .event-title { display:flex; align-items:center; justify-content:space-between; gap:10px; }
   .event-agent { font-size:14px; font-weight:760; }
   .event-type { color:var(--muted); font-size:12px; font-family:ui-monospace, monospace; }
+  .trace-pair {
+    margin-top:9px; display:grid; grid-template-columns:minmax(0,1fr) minmax(0,1fr);
+    gap:8px;
+  }
+  .lane {
+    min-width:0; border:1px solid #2b2f2e; background:#151717; border-radius:8px;
+    padding:10px;
+  }
+  .lane.agent-lane { border-color:#33403f; }
+  .lane.debug-lane { border-color:#3a3430; background:#181713; }
+  .event.root .lane.debug-lane { border-color:#80612d; background:#211a11; }
+  .lane-head { display:flex; align-items:center; justify-content:space-between; gap:8px; }
+  .lane-label {
+    color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:0;
+  }
+  .lane-title { margin-top:6px; color:#f1f2ee; font-size:13px; line-height:1.3; font-weight:720; }
+  .lane-copy { margin-top:7px; color:#d9ddd5; font-size:12px; line-height:1.45; overflow-wrap:anywhere; }
+  .lane-meta { margin-top:9px; display:flex; gap:6px; flex-wrap:wrap; }
+  .trace-link {
+    margin-top:8px; color:var(--muted); font-size:11px; line-height:1.4;
+    font-family:ui-monospace, SFMono-Regular, Consolas, monospace;
+  }
   .event-grid { margin-top:8px; display:grid; grid-template-columns:1fr 1fr; gap:8px; }
   .field { min-width:0; border:1px solid #2b2f2e; background:#151717; border-radius:8px; padding:9px; }
-  .field-label { color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:.08em; }
+  .field-label { color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:0; }
   .field-value { margin-top:5px; color:#d9ddd5; font-size:12px; line-height:1.4;
     overflow-wrap:anywhere; }
   .field.error { border-color:#66333a; background:#211619; }
@@ -265,7 +309,7 @@ _INDEX_HTML = """<!doctype html>
   .root-card { border-left:4px solid var(--amber); }
   .root-grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:8px; margin-top:10px; }
   .mini { border:1px solid #303434; border-radius:8px; padding:9px; background:#171919; min-width:0; }
-  .mini-label { color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:.08em; }
+  .mini-label { color:var(--muted2); font-size:10px; text-transform:uppercase; letter-spacing:0; }
   .mini-value { margin-top:6px; font-size:13px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
   .flow { display:grid; gap:8px; }
   .flow-item {
@@ -284,6 +328,7 @@ _INDEX_HTML = """<!doctype html>
     .sidebar { border-right:0; border-bottom:1px solid var(--line); }
     .workspace { height:auto; }
     .topbar { position:static; }
+    .trace-legend, .trace-pair { grid-template-columns:1fr; }
   }
 </style>
 </head>
@@ -324,6 +369,7 @@ _INDEX_HTML = """<!doctype html>
   </section>
 </div>
 <script>
+const BOOTSTRAP = __BOOTSTRAP_JSON__;
 async function api(path) {
   const r = await fetch(path);
   if (!r.ok) throw new Error('HTTP ' + r.status);
@@ -367,6 +413,20 @@ async function loadTraceList() {
     document.getElementById('detail').innerHTML = '<div class="empty">No traces in store.</div>';
   }
 }
+function renderTraceList(traceIds, selectedId) {
+  const ul = document.getElementById('trace-list');
+  ul.innerHTML = '';
+  document.getElementById('trace-count').textContent = traceIds.length + ' trace' + (traceIds.length === 1 ? '' : 's') + ' in local store';
+  traceIds.forEach((tid) => {
+    const li = document.createElement('li');
+    li.className = 'run' + (tid === selectedId ? ' active' : '');
+    li.innerHTML = '<div class="run-id">' + escapeHtml(tid) + '</div>' +
+      '<div class="run-meta"><span class="chip bad">failed</span><span class="chip">SQLite</span></div>';
+    li.dataset.tid = tid;
+    li.onclick = () => { selectTrace(tid, li); };
+    ul.appendChild(li);
+  });
+}
 async function selectTrace(tid, li) {
   document.querySelectorAll('.run').forEach(el => el.classList.remove('active'));
   li.classList.add('active');
@@ -403,8 +463,11 @@ function renderTrace(traj, report) {
   html += '</div></div>';
 
   html += '<div class="layout">';
-  html += '<div class="panel"><div class="panel-head"><div class="panel-title">Execution Timeline</div><span class="chip">who / when / evidence</span></div><div class="panel-body"><div class="timeline">';
-  for (const ev of events) html += renderEvent(ev, ev.event_id === rootId);
+  html += '<div class="panel"><div class="panel-head"><div class="panel-title">Agent Trace + Error Trace Alignment</div><span class="chip">native span -> diagnosis</span></div><div class="panel-body">';
+  html += '<div class="trace-legend"><div class="legend-cell"><div class="legend-label">Agent native trace</div><div class="legend-title">What the agent logged, thought, called, or observed.</div></div>';
+  html += '<div class="legend-cell"><div class="legend-label">AgentDebugX error trace</div><div class="legend-title">Normalized failure signal, attribution, and repair hint for human review.</div></div></div>';
+  html += '<div class="timeline">';
+  for (const ev of events) html += renderEvent(ev, ev.event_id === rootId, findingForEvent(findings, ev.event_id));
   html += '</div></div></div>';
 
   html += '<div class="rail">';
@@ -440,13 +503,61 @@ function mini(label, value) {
 function flow(n, text) {
   return '<div class="flow-item"><div class="flow-dot">' + n + '</div><div>' + escapeHtml(text) + '</div></div>';
 }
-function renderEvent(ev, isRoot) {
+function findingForEvent(findings, eventId) {
+  return (findings || []).find(f => f.event_id === eventId) || null;
+}
+function nativeTrace(ev) {
+  const meta = ev.metadata || {};
+  const native = meta.native_trace || {};
+  const fallback = truncate(ev.output || ev.input || ev.error || 'Recorded framework event.', 180);
+  const tags = Array.isArray(native.tags) ? native.tags : [ev.module || 'module', ev.event_type || 'event'];
+  return {
+    span: native.span_id || ev.event_id || '-',
+    title: native.title || ((ev.agent_name || 'agent') + ' / ' + (ev.event_type || 'event')),
+    body: native.message || fallback,
+    tags: tags,
+    state: native.state || native.tool || ''
+  };
+}
+function errorTrace(ev, finding) {
+  const meta = ev.metadata || {};
+  const overlay = meta.error_trace || {};
+  const mode = overlay.failure_mode || finding?.failure_mode?.mode_id || (eventProblem(ev) ? 'unclassified.signal' : 'context');
+  const title = overlay.title || finding?.failure_mode?.name || (eventProblem(ev) ? 'Failure signal detected' : 'Context event');
+  const body = overlay.human_readout || finding?.suggestion || (eventProblem(ev)
+    ? 'AgentDebugX keeps this event in the failure trace because it contains an error, lost-context signal, or invalid state transition.'
+    : 'No local failure signal; shown to preserve the causal path for the reviewer.');
+  const severity = overlay.severity || (finding ? 'high' : (eventProblem(ev) ? 'medium' : 'context'));
+  const repair = overlay.repair || finding?.suggestion || '';
+  return {mode, title, body, severity, repair};
+}
+function severityClass(severity) {
+  if (severity === 'critical' || severity === 'high') return 'bad';
+  if (severity === 'medium') return 'warn';
+  if (severity === 'context') return '';
+  return 'cyan';
+}
+function renderEvent(ev, isRoot, finding) {
+  const native = nativeTrace(ev);
+  const debug = errorTrace(ev, finding);
   let html = '<div class="event ' + (isRoot ? 'root' : '') + '">';
   html += '<div class="step-index">' + escapeHtml(ev.step_index ?? '-') + '</div>';
   html += '<div><div class="event-title"><div><div class="event-agent">' + escapeHtml(ev.agent_name || 'agent') + '</div>';
   html += '<div class="event-type">' + escapeHtml(ev.event_type || '') + ' / ' + escapeHtml(ev.module || 'module') + '</div></div>';
   html += isRoot ? '<span class="chip warn">root candidate</span>' : (eventProblem(ev) ? '<span class="chip bad">signal</span>' : '<span class="chip good">ok</span>');
-  html += '</div><div class="event-grid">';
+  html += '</div><div class="trace-pair">';
+  html += '<div class="lane agent-lane"><div class="lane-head"><div class="lane-label">Agent native trace</div><span class="chip">' + escapeHtml(native.span) + '</span></div>';
+  html += '<div class="lane-title">' + escapeHtml(native.title) + '</div>';
+  html += '<div class="lane-copy">' + escapeHtml(native.body) + '</div>';
+  html += '<div class="lane-meta">' + (native.tags || []).map(t => '<span class="chip">' + escapeHtml(t) + '</span>').join('') + '</div>';
+  if (native.state) html += '<div class="trace-link">' + escapeHtml(native.state) + '</div>';
+  html += '</div>';
+  html += '<div class="lane debug-lane"><div class="lane-head"><div class="lane-label">AgentDebugX error trace</div><span class="chip ' + severityClass(debug.severity) + '">' + escapeHtml(debug.severity) + '</span></div>';
+  html += '<div class="lane-title">' + escapeHtml(debug.title) + '</div>';
+  html += '<div class="lane-copy">' + escapeHtml(debug.body) + '</div>';
+  html += '<div class="lane-meta"><span class="chip ' + (finding ? familyClass(finding.failure_mode?.family) : '') + '">' + escapeHtml(debug.mode) + '</span></div>';
+  if (debug.repair) html += '<div class="trace-link">repair: ' + escapeHtml(debug.repair) + '</div>';
+  html += '</div></div><div class="event-grid">';
   html += field('Input', truncate(ev.input, 132), false);
   html += field('Output', truncate(ev.output, 132), false);
   html += field('Error', truncate(ev.error, 132), Boolean(ev.error));
@@ -469,6 +580,15 @@ function renderFinding(f) {
   html += '</div>';
   return html;
 }
+if (BOOTSTRAP && BOOTSTRAP.traces) {
+  const selected = BOOTSTRAP.selected ? BOOTSTRAP.selected.trajectory.trace_id : null;
+  renderTraceList(BOOTSTRAP.traces, selected);
+  if (BOOTSTRAP.selected) {
+    renderTrace(BOOTSTRAP.selected.trajectory, BOOTSTRAP.selected.report);
+  } else {
+    document.getElementById('detail').innerHTML = '<div class="empty">No traces in store.</div>';
+  }
+}
 loadTraceList();
 </script>
 </body>