Crate agx_core 

agx-core — pure parsers, timeline model, and analytics for the agx step-through-debugger CLI.

This crate is the TUI-free half of the agx repo. It ships the parsers for every supported agent-trace format (Claude Code, Codex, Gemini, OpenAI-compatible, LangChain, Vercel AI SDK, OpenTelemetry GenAI — JSON + optional binary), the shared timeline::Step model, cost estimation, corpus aggregation, export writers, annotation storage, and the PII scanner.

The TUI layer lives in the top-level agx crate, which consumes this library. Integrators who want to drive agx’s parsers programmatically — eval harnesses, custom CI guards, lightweight dashboards — can depend on agx-core without pulling in ratatui / crossterm / arboard.

Stability

Public API tracks the stepwise-suite conventions in docs/suite-conventions.md §5. Schema-breaking changes to timeline::Step field names, format::Format variants, or the --export json shape (mirrored here through export::json) require a minor-version bump and a note in the main crate’s README compat table. New fields may appear; removals or renames are breaking.

Entry point

use agx_core::loader::load_session;
let steps = load_session(Path::new("session.jsonl"))?;
for step in &steps {
    println!("{:?} {}", step.kind, step.label);
}

Modules

annotations

Per-step annotations — the first persistent write-back feature.

browser

codex

corpus

Corpus-level analytics for agx corpus <dir>. Walks a directory tree, loads every session file it finds in parallel, and aggregates cross-session stats (tokens, cost, per-model / per-tool / per-format breakdowns).

debug_unknowns

Format-drift diagnostics: scan a session file and report any entry types or content-item types the typed parsers don’t recognize.

diff_align

Session-to-session alignment. Pure-algorithm module with no TUI dependencies — all rendering lives in diff_tui.rs. Kept separate so the alignment logic can be unit-tested cleanly and reused for non-TUI diff modes later.

export

Session export — produces Markdown, HTML, or JSON representations of a parsed timeline. Used by the --export md|html|json flag.

format

gemini

generic

langchain

LangChain / LangSmith trace parser. Reads the single-JSON export shape that LangSmith produces via the “export run” button and that LangChain’s tracer emits when writing a full run tree to a file.

loader

Session-loading front door. Takes a path, detects the format, calls the right parser, returns Vec<Step>. Lives in its own module so both the single-session TUI/summary path (in main.rs) and the corpus subcommand (in corpus.rs) dispatch through the same function.

notify

Desktop notifications for --live mode — fires when the watched session grows with a new error tool_result, or when it stops growing for a user-specified duration. Opt-in via --features notifications.

otel_json

OpenTelemetry GenAI parser — reads OTLP-JSON trace exports produced by otel-desktop-viewer, otel-cli export, and direct application/json OTLP endpoints. Maps OTel GenAI semantic-convention attributes into the shared timeline::Step model.

otel_proto

Binary OTLP (.pb / .otlp) parser — reads protobuf-encoded OpenTelemetry trace exports.

pii

Heuristic PII / credential scanner for --scan-pii. Reports matches, does not mutate — pair with --redact when the intent is to scrub.

pricing

Per-model pricing lookup. Converts a Step’s token counters into a USD cost estimate.

semantic

Semantic search over session steps — opt-in via --features embedding-search.

session

slice

Timeline slicing — parsers + application for --after / --before duration filters, --after-step / --before-step / --range index filters, and the :@<duration> TUI jump command.

timeline

vercel_ai

Vercel AI SDK trace parser. Reads the single-JSON result objects that generateText / streamText produce when stringified — the shape most backends actually save to disk.