cctx-cli 1.11.0__tar.gz → 1.12.0__tar.gz

{cctx_cli-1.11.0 → cctx_cli-1.12.0}/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 <!-- version list -->
 
+## v1.12.0 (2026-06-20)
+
+### Bug Fixes
+
+- Otel parser — per-trace warnings, multiple-root warning, full span list for subagent turns
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Ruff F401 + I001 in test_otel_parser.py ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Documentation
+
+- OTEL parser design spec — OpenAI Agents SDK support via parsers/otel.py
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser implementation plan ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Quickstart guide for OpenAI Agents SDK + cctx OTEL integration
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Features
+
+- _detect_source() — auto-detect Claude Code vs OTEL trace format
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OpenAI Agents SDK support via OTEL parser ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser skeleton — span loading and session trace construction
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Wire OTEL auto-detection into autopsy — cctx autopsy <otel.jsonl> just works
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Testing
+
+- Add OTLP JSONL fixtures for otel parser (handoff + fanout)
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser error handling — malformed JSON, unknown spans, empty file
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify child AgentSpan → subagents mapping (handoff + fan-out)
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify FunctionSpan → ToolUse + ToolResult mapping
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify GenerationSpan → Turn mapping for OTEL parser
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+
 ## v1.11.0 (2026-06-11)
 
 ### Bug Fixes

{cctx_cli-1.11.0 → cctx_cli-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.11.0
+Version: 1.12.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-1.11.0 → cctx_cli-1.12.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "1.11.0"
+__version__ = "1.12.0"

{cctx_cli-1.11.0 → cctx_cli-1.12.0}/cctx/cli.py

@@ -13,6 +13,7 @@ Commands:
 """
 from __future__ import annotations
 
+import json as _json
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import IO
@@ -179,6 +180,48 @@ def _render_check_findings(findings: list, target_dir: Path) -> None:
         con.print(f"  {badge:<6}  {f.heading}  {label}: {f.detail}")
 
 
+_CLAUDE_CODE_LINE_TYPES = frozenset({
+    "user", "assistant", "system", "attachment",
+    "last-prompt", "permission-mode", "ai-title", "custom-title",
+    "queue-operation", "file-history-snapshot", "pr-link",
+})
+
+
+def _detect_source(path: Path) -> str:
+    """Sniff first non-empty lines to detect trace format.
+
+    Returns "claude_code" or "otel".
+    Raises click.UsageError if the format cannot be determined.
+    """
+    try:
+        with path.open(encoding="utf-8", errors="replace") as f:
+            for _ in range(5):
+                line = f.readline()
+                if not line:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = _json.loads(line)
+                except _json.JSONDecodeError:
+                    continue
+                if "resourceSpans" in obj:
+                    return "otel"
+                if "traceId" in obj and "spanId" in obj:
+                    return "otel"
+                line_type = obj.get("type")
+                if isinstance(line_type, str) and line_type in _CLAUDE_CODE_LINE_TYPES:
+                    return "claude_code"
+    except OSError as exc:
+        raise click.UsageError(f"Cannot read file: {path}: {exc}") from exc
+
+    raise click.UsageError(
+        f"Cannot determine trace format for {path}.\n"
+        "Expected a Claude Code JSONL session file or an OTLP JSON trace export."
+    )
+
+
 @click.group()
 def cli() -> None:
     """cctx — find out why your Claude Code session went sideways."""
@@ -415,7 +458,15 @@ def autopsy(
                 "TARGET is a directory. Use --since N for cross-session mode, "
                 "or pass a .jsonl file directly."
             )
-        trace = tokenize_session(parse_session(target))
+        source = _detect_source(target)
+        if source == "otel":
+            from cctx.parsers.otel import parse_otel_file as _parse_otel_file
+            otel_traces = _parse_otel_file(target)
+            if not otel_traces:
+                raise click.UsageError(f"No traces found in {target}")
+            trace = tokenize_session(otel_traces[0])
+        else:
+            trace = tokenize_session(parse_session(target))
         diagnosis = diagnostician.run(trace)
         diagnosis = claude_md.generate(diagnosis)
         if quiet:

cctx_cli-1.12.0/cctx/parsers/otel.py

@@ -0,0 +1,346 @@
+"""OTLP JSONL parser for OpenAI Agents SDK traces.
+
+Public API:
+    parse_otel_file(path: Path) -> list[SessionTrace]
+
+Reads OTLP JSON (one ResourceSpans batch per line). Maps spans to the
+cctx canonical model. No imports from anthropic, click, or other cctx
+modules except cctx.models.
+"""
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cctx.models import (
+    ParserWarning,
+    SessionTrace,
+    ToolResult,
+    ToolUse,
+    Turn,
+    Usage,
+)
+
+
+def parse_otel_file(path: Path) -> list[SessionTrace]:
+    """Read an OTLP JSONL export; return one SessionTrace per trace_id."""
+    path = Path(path)
+    load_warnings: list[ParserWarning] = []
+    spans = _load_spans(path, load_warnings)
+
+    by_trace: dict[str, list[dict]] = defaultdict(list)
+    for span in spans:
+        trace_id = span.get("traceId", "")
+        if trace_id:
+            by_trace[trace_id].append(span)
+
+    traces = []
+    for trace_id, trace_spans in by_trace.items():
+        # Each trace gets its own warnings list; load-time warnings are copied in.
+        trace_warnings = list(load_warnings)
+        traces.append(_build_session_trace(trace_id, trace_spans, path, trace_warnings))
+    return traces
+
+
+def _load_spans(path: Path, warnings: list[ParserWarning]) -> list[dict]:
+    """Load all spans from OTLP JSONL. One ResourceSpans JSON object per line."""
+    spans: list[dict] = []
+    try:
+        with path.open(encoding="utf-8", errors="replace") as f:
+            for lineno, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    warnings.append(
+                        ParserWarning(
+                            code="malformed_json",
+                            detail=f"skipped malformed JSON on line {lineno}",
+                            line_number=lineno,
+                            path=path,
+                        )
+                    )
+                    continue
+                for rs in obj.get("resourceSpans", []):
+                    for ss in rs.get("scopeSpans", []):
+                        for span in ss.get("spans", []):
+                            span["_resource"] = rs.get("resource", {})
+                            spans.append(span)
+    except OSError as exc:
+        warnings.append(
+            ParserWarning(code="read_error", detail=str(exc), path=path)
+        )
+    return spans
+
+
+def _build_session_trace(
+    trace_id: str,
+    spans: list[dict],
+    source_path: Path,
+    warnings: list[ParserWarning],
+) -> SessionTrace:
+    root = _find_root_agent_span(spans, warnings)
+    if root is None:
+        root = {}
+
+    turns = _build_turns(root, spans)
+    subagents = _build_subagents(root, spans, source_path, warnings)
+    primary_model = _primary_model(spans)
+    cwd = _attr_str(root, "process.cwd") or ""
+
+    all_start_times = [
+        _nano_to_dt(s.get("startTimeUnixNano"))
+        for s in spans
+        if s.get("startTimeUnixNano")
+    ]
+    start_time = min((t for t in all_start_times if t), default=None)
+    all_end_times = [
+        _nano_to_dt(s.get("endTimeUnixNano"))
+        for s in spans
+        if s.get("endTimeUnixNano")
+    ]
+    end_time = max((t for t in all_end_times if t), default=None)
+
+    tool_names: list[str] = list({
+        name
+        for s in spans
+        if _attr_str(s, "gen_ai.operation.name") == "invoke_function"
+        if (name := _attr_str(s, "gen_ai.tool.name"))
+    })
+
+    return SessionTrace(
+        session_id=trace_id,
+        parent_session_id=None,
+        project_path="",
+        cwd=cwd,
+        primary_model=primary_model,
+        claude_code_version=None,
+        turns=turns,
+        subagents=subagents,
+        attachments=[],
+        raw_tool_result_files=[],
+        initial_context_tokens=0,
+        tool_names_loaded=tool_names,
+        start_time=start_time,
+        end_time=end_time,
+        source_path=source_path,
+        subagent_meta={},
+        warnings=warnings,
+        subagent_parse_errors=[],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Span tree helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_root_agent_span(
+    spans: list[dict], warnings: list[ParserWarning]
+) -> dict | None:
+    roots = [
+        s for s in spans
+        if _attr_str(s, "gen_ai.operation.name") == "run_agent"
+        and not s.get("parentSpanId")
+    ]
+    if not roots:
+        warnings.append(
+            ParserWarning(code="no_root_agent_span", detail="no root AgentSpan found")
+        )
+        return None
+    if len(roots) > 1:
+        span_ids = ", ".join(r.get("spanId", "?") for r in roots)
+        warnings.append(
+            ParserWarning(
+                code="multiple_root_agent_spans",
+                detail=f"found {len(roots)} root AgentSpans; using first: {span_ids}",
+            )
+        )
+    return roots[0]
+
+
+def _build_turns(agent_span: dict, all_spans: list[dict]) -> list[Turn]:
+    """Build assistant turns from GenerationSpans that are direct children of agent_span."""
+    if not agent_span:
+        return []
+    agent_id = agent_span.get("spanId", "")
+    gen_spans = [
+        s for s in all_spans
+        if s.get("parentSpanId") == agent_id
+        and _attr_str(s, "gen_ai.operation.name") == "chat"
+    ]
+    gen_spans.sort(key=lambda s: int(s.get("startTimeUnixNano") or 0))
+
+    turns: list[Turn] = []
+    for i, gs in enumerate(gen_spans, 1):
+        tool_uses, tool_results = _build_tool_uses(gs, all_spans)
+        usage = Usage(
+            input_tokens=_attr_int(gs, "gen_ai.usage.input_tokens") or 0,
+            output_tokens=_attr_int(gs, "gen_ai.usage.output_tokens") or 0,
+            cache_creation_5m=0,
+            cache_creation_1h=0,
+            cache_read=0,
+            service_tier=None,
+        )
+        ts = _nano_to_dt(gs.get("startTimeUnixNano")) or datetime.now(timezone.utc)
+        end_ns = gs.get("endTimeUnixNano")
+        start_ns = gs.get("startTimeUnixNano")
+        duration_ms: int | None = None
+        if end_ns and start_ns:
+            duration_ms = int((int(end_ns) - int(start_ns)) / 1_000_000)
+
+        turns.append(
+            Turn(
+                turn_number=i,
+                uuid=gs.get("spanId", ""),
+                parent_uuid=agent_id or None,
+                role="assistant",
+                text=_attr_str(gs, "gen_ai.output.text") or "",
+                thinking="",
+                tool_uses=tool_uses,
+                tool_results=tool_results,
+                usage=usage,
+                model=_attr_str(gs, "gen_ai.request.model"),
+                stop_reason="end_turn",
+                timestamp=ts,
+                duration_ms=duration_ms,
+            )
+        )
+    return turns
+
+
+def _build_tool_uses(
+    gen_span: dict, all_spans: list[dict]
+) -> tuple[list[ToolUse], list[ToolResult]]:
+    """Extract ToolUse + ToolResult from FunctionSpan children of a GenerationSpan."""
+    gen_id = gen_span.get("spanId", "")
+    func_spans = [
+        s for s in all_spans
+        if s.get("parentSpanId") == gen_id
+        and _attr_str(s, "gen_ai.operation.name") == "invoke_function"
+    ]
+    func_spans.sort(key=lambda s: int(s.get("startTimeUnixNano") or 0))
+
+    tool_uses: list[ToolUse] = []
+    tool_results: list[ToolResult] = []
+    for fs in func_spans:
+        tool_name = _attr_str(fs, "gen_ai.tool.name") or "unknown"
+        call_id = _attr_str(fs, "gen_ai.tool.call.id") or fs.get("spanId", "")
+        result_str = _attr_str(fs, "gen_ai.tool.call.result") or ""
+        is_error = fs.get("status", {}).get("code", 1) == 2  # OTEL STATUS_ERROR = 2
+
+        tool_uses.append(ToolUse(tool_name=tool_name, tool_use_id=call_id, tool_input={}))
+        tool_results.append(
+            ToolResult(
+                tool_name=tool_name,
+                tool_use_id=call_id,
+                content=result_str,
+                structured=None,
+                is_error=is_error,
+            )
+        )
+    return tool_uses, tool_results
+
+
+def _build_subagents(
+    root_span: dict,
+    all_spans: list[dict],
+    source_path: Path,
+    warnings: list[ParserWarning],
+) -> list[SessionTrace]:
+    """Build child SessionTraces from child AgentSpans (handoffs + parallel sub-agents)."""
+    if not root_span:
+        return []
+    root_id = root_span.get("spanId", "")
+    child_agent_spans = [
+        s for s in all_spans
+        if s.get("parentSpanId") == root_id
+        and _attr_str(s, "gen_ai.operation.name") == "run_agent"
+    ]
+    child_agent_spans.sort(key=lambda s: int(s.get("startTimeUnixNano") or 0))
+
+    subagents: list[SessionTrace] = []
+    for child in child_agent_spans:
+        child_id = child.get("spanId", "")
+        # child_spans: direct children only (used for primary_model / time bounds).
+        # _build_turns receives the full all_spans list so _build_tool_uses can
+        # locate FunctionSpan grandchildren regardless of nesting depth.
+        child_spans = [s for s in all_spans if s.get("parentSpanId") == child_id]
+        agent_name = _attr_str(child, "gen_ai.agent.name") or child_id
+        child_turns = _build_turns(child, all_spans)
+        child_start = _nano_to_dt(child.get("startTimeUnixNano"))
+        child_end = _nano_to_dt(child.get("endTimeUnixNano"))
+
+        subagents.append(
+            SessionTrace(
+                session_id=child_id,
+                parent_session_id=root_id or None,
+                project_path="",
+                cwd="",
+                primary_model=_primary_model(child_spans),
+                claude_code_version=None,
+                turns=child_turns,
+                subagents=[],
+                attachments=[],
+                raw_tool_result_files=[],
+                initial_context_tokens=0,
+                tool_names_loaded=[],
+                start_time=child_start,
+                end_time=child_end,
+                source_path=source_path,
+                subagent_meta={"agent_name": agent_name},
+                warnings=[],
+                subagent_parse_errors=[],
+            )
+        )
+    return subagents
+
+
+# ---------------------------------------------------------------------------
+# Attribute + time helpers
+# ---------------------------------------------------------------------------
+
+
+def _primary_model(spans: list[dict]) -> str | None:
+    models = [
+        m for s in spans
+        if _attr_str(s, "gen_ai.operation.name") == "chat"
+        if (m := _attr_str(s, "gen_ai.request.model"))
+    ]
+    if not models:
+        return None
+    return max(set(models), key=models.count)
+
+
+def _attr_str(span: dict, key: str) -> str | None:
+    for attr in span.get("attributes", []):
+        if attr.get("key") == key:
+            return attr.get("value", {}).get("stringValue")
+    return None
+
+
+def _attr_int(span: dict, key: str) -> int | None:
+    for attr in span.get("attributes", []):
+        if attr.get("key") == key:
+            val = attr.get("value", {})
+            raw = val.get("intValue") or val.get("doubleValue")
+            if raw is not None:
+                try:
+                    return int(float(raw))
+                except (ValueError, TypeError):
+                    return None
+    return None
+
+
+def _nano_to_dt(nano: str | int | None) -> datetime | None:
+    if nano is None:
+        return None
+    try:
+        ns = int(nano)
+        return datetime.fromtimestamp(ns / 1e9, tz=timezone.utc)
+    except (ValueError, TypeError, OSError):
+        return None

cctx_cli-1.12.0/docs/quickstart-openai-agents.md

@@ -0,0 +1,106 @@
+# Using cctx with the OpenAI Agents SDK
+
+cctx diagnoses OpenAI Agents SDK runs the same way it diagnoses Claude Code sessions — point it at a trace file and get an autopsy.
+
+## 1. Install dependencies
+
+```bash
+pip install cctx opentelemetry-sdk
+```
+
+## 2. Export traces to a local file
+
+Add this to your agent script before running your agent. It configures OpenTelemetry to write spans to a local JSONL file.
+
+```python
+import json
+from typing import Sequence
+
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace.export import ReadableSpan
+
+
+class FileSpanExporter(SpanExporter):
+    """Writes OTLP-style JSON batches to a local file, one line per flush."""
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        batch = {
+            "resourceSpans": [{
+                "resource": {"attributes": []},
+                "scopeSpans": [{
+                    "scope": {"name": "openai.agents"},
+                    "spans": [self._span_to_dict(s) for s in spans],
+                }],
+            }]
+        }
+        with open(self._path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(batch) + "\n")
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        pass
+
+    @staticmethod
+    def _span_to_dict(span: ReadableSpan) -> dict:
+        ctx = span.context
+        attrs = [
+            {"key": k, "value": _otlp_value(v)}
+            for k, v in (span.attributes or {}).items()
+        ]
+        d: dict = {
+            "traceId": format(ctx.trace_id, "032x"),
+            "spanId": format(ctx.span_id, "016x"),
+            "name": span.name,
+            "kind": int(span.kind),
+            "startTimeUnixNano": str(span.start_time),
+            "endTimeUnixNano": str(span.end_time),
+            "attributes": attrs,
+            "status": {"code": span.status.status_code.value},
+        }
+        if span.parent is not None:
+            d["parentSpanId"] = format(span.parent.span_id, "016x")
+        return d
+
+
+def _otlp_value(v: object) -> dict:
+    if isinstance(v, bool):
+        return {"boolValue": v}
+    if isinstance(v, int):
+        return {"intValue": str(v)}
+    if isinstance(v, float):
+        return {"doubleValue": v}
+    return {"stringValue": str(v)}
+
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(FileSpanExporter("agent_trace.jsonl")))
+
+# Wire into the OpenAI Agents SDK — exact API depends on your SDK version:
+# from agents import set_trace_processors
+# set_trace_processors([...])
+```
+
+## 3. Run your agent
+
+```bash
+python my_agent.py
+# agent_trace.jsonl is written
+```
+
+## 4. Diagnose the run
+
+```bash
+cctx autopsy agent_trace.jsonl
+```
+
+`cctx autopsy` picks up the OTLP format automatically — no flags needed.
+
+## Notes
+
+- If your trace file contains multiple runs, cctx diagnoses the first trace by trace ID.
+- Token costs shown in the autopsy are estimates; cctx does not call the OpenAI API.
+- The exact `set_trace_processors` API varies by SDK version — check the `openai-agents` changelog if the import above doesn't work.