Skip to main content

Trajectory Fidelity Bridge

CI

Move structured coding-agent history between tools without collapsing it into a prose summary.

Trajectory Fidelity Bridge (TFB) converts supported coding-agent transcripts into the Agent Trajectory Interchange Format (ATIF), a shared format for conversations, tool calls, and results. Its fidelity report counts supported and omitted material so you can inspect what survived conversion.

Canonical project page · PyPI · Open issues · Architecture

Trajectory Fidelity Bridge is an MIT-licensed reference implementation for converting supported coding-agent transcripts into the Agent Trajectory Interchange Format (ATIF). It is not a competing interchange standard.

Current status: Claude Code transcripts and a bounded subset of Codex session rollouts can be normalized to ATIF v1.7. TFB includes heuristic secret redaction, fidelity reporting, and an Antigravity derived-log mapping. It cannot import its generated trajectories into native Antigravity sessions.

External validation wanted: sanitized provider fixtures that expose a normalization failure, disagreements with the fidelity report, evidence about additional documented ingestion boundaries, and reproducible cross-provider transformation cases are especially useful. Open an issue with the smallest safe fixture that demonstrates the problem.

Trajectory Fidelity Bridge quick tour

Animated architecture tour based on documented behavior; it is not a fabricated live screen recording.

What ATIF provides and what TFB adds

ATIF is the portable trajectory layer: ordered system/user/agent steps, structured tool calls, call-correlated observations, agent metadata, metrics, and a namespaced extra extension mechanism. TFB converts provider-specific transcript shapes into that public format.

TFB's distinct responsibilities are deliberately narrower:

  • provider-specific parsing and normalization;
  • best-effort secret redaction before export;
  • transformation/fidelity accounting in extra.agent_session_bridge;
  • target-specific mappings, such as the observed Antigravity derived-log shape; and
  • explicit refusal to fabricate native resumable session state.

The current Antigravity reference mapper reports any ATIF system messages it cannot map to the observed derived-log shape; it does not silently invent a target record type.

See the ATIF mapping and layered architecture for exact preserved, transformed, and unsupported semantics.

Non-string Claude record types and message roles are reported as unsupported records, allowing conversion to continue to later valid records. Other malformed fields may still prevent conversion; inspect the fidelity report and output.

The reproducible synthetic interoperability corpus, semantic oracle, adversarial verifier, current ATIF v1.8 audit, and cross-converter evidence are documented in docs/INTEROPERABILITY.md. A passing corpus check is not independent practitioner validation or proof of universal provider compatibility.

What works today

Capability Status Notes
Claude Code JSONL import ✅ Parses supported message and tool structures into ATIF v1.7
Codex rollout JSONL import ✅ bounded Preserves supported messages and tool/result links; unsupported events are counted
Portable interchange document ✅ Validated by the official atif Python models
TFB fidelity reporting ✅ Namespaced provenance and unsupported/degraded source counts in ATIF extra
Human-readable session report ✅ tfb explain renders an ATIF file as Markdown, with what the conversion could not preserve
Heuristic secret redaction ✅ Best effort only; output still requires human review
Antigravity derived-log mapping ✅ Reference payload based on observed transcript.jsonl structures
Native Antigravity session import ❌ unsupported TFB cannot create or resume a native session from its reference payload

Quick start

Python 3.11 or newer is required. The package is named atomicdjt-trajectory-fidelity-bridge on PyPI, and its primary command is tfb.

Install the published package:

python -m pip install atomicdjt-trajectory-fidelity-bridge

Convert a Claude Code JSONL transcript to ATIF, then write a readable report:

tfb import --from claude-code --source your_claude_log.jsonl --output trajectory.atif.json --report
tfb explain trajectory.atif.json --output report.md

For the repository's synthetic sample, the import command's --report produces:

--- TFB Fidelity Report ---
Source records preserved: 4
Tool calls preserved:     1
Observations preserved:   1
Unsupported records:      0
Unsupported blocks:       0
---------------------------

These are counts for that fixture, not a guarantee that every part of a transcript survived. The ATIF output contains a more detailed accounting, including omitted timestamps and orphaned results. Review the report and output before sharing; redaction is best effort.

For a Codex recorded session rollout, use --from codex instead:

tfb import --from codex --source rollout.jsonl --output trajectory.atif.json --report
tfb explain trajectory.atif.json --output report.md

This accepts a bounded subset of recorded Codex rollout JSONL, not the codex exec --json live event stream. See the supported fields and limitations and the synthetic example. The convert reference mapping below currently accepts Claude Code only.

To generate an Antigravity-shaped reference payload from a Claude Code transcript:

tfb convert --from claude-code --to antigravity your_claude_log.jsonl

This produces a derived log; it does not import or resume a session in Antigravity. The older tfb handoff command remains available for compatibility and reports UnsupportedNativeImport; it cannot perform a native handoff.

The earlier agent-session command is an alias for tfb. The extra.agent_session_bridge extension key and the older atomicdjt-agent-session-bridge distribution are retained for compatibility. The shorter PyPI name agent-session-bridge belongs to an unrelated project. See the migration guide.

Source-level facts that ATIF does not carry (source hash, converter version, capture time) are shown only if you supply them in an optional --manifest JSON file, and are then labelled as unverified. fixtures/real-session/ is a sanitized ATIF trajectory and manifest from one controlled, real Claude Code session with synthetic content; it demonstrates this path, not general compatibility. See docs/DEMO_REAL_SESSION.md for the private, reproducible procedure that produced it.

Architecture

provider transcript
       │
       ▼
source parser and normalizer
       │
       ▼
ATIF trajectory ─────► TFB provenance/fidelity extension
       │
       ├──────────────► redacted portable trajectory
       │
       ▼
target-specific mapper
       │
       ▼
target payload / supported importer, if one exists

ATIF makes a trajectory portable; it does not require target runtimes to ingest it as native state. Native resumption remains a target-owned capability, with target-owned validation, persistence, and security constraints.

Fidelity and security boundaries

For the current Claude Code adapter, TFB preserves supported roles, valid ISO-8601 step timestamps, text, tool names, tool arguments, and tool results. It normalizes later Claude tool_result blocks into ATIF observations attached to their originating calls. Unsupported source records or blocks are counted in extra.agent_session_bridge.fidelity; they are never represented as successfully preserved. ATIF v1.7 has no timestamp on an observation result, so tool-result timestamps are not carried into the output; they are counted as omitted_tool_result_timestamps and no time is ever invented (details).

  • Imported history is processed as data. Historical commands are never executed.
  • Redaction is heuristic and is not a guarantee; see what it does and does not cover.
  • Do not publish a converted transcript without reviewing it for credentials, personal data, private source, or proprietary context.
  • TFB does not reverse-engineer or write Antigravity's opaque internal session database.

Optional observability projection

The observability implementation is an optional downstream projection of ATIF, not a replacement for ATIF, and not original runtime instrumentation. It can read an ATIF document produced by another tool, subject to TFB's supported ATIF fields and error-flag conventions. It is a historical structural projection.

provider transcript
        ↓
Trajectory Fidelity Bridge
        ↓
ATIF v1.7
        ↓
historical observability projection
        ↓
OpenTelemetry / OpenInference
        ↓
OTLP
        ↓
Phoenix or another compatible backend

To install the optional observability dependencies:

python -m pip install "atomicdjt-trajectory-fidelity-bridge[observability]"

For the local Phoenix example, Phoenix may be installed separately. It is not required for core Trajectory Fidelity Bridge operation:

python -m pip install arize-phoenix

A Claude Code source may also be observed using the existing supported --from claude-code path where appropriate.

tfb observe trajectory.atif.json \
  --from atif \
  --backend phoenix \
  --endpoint http://127.0.0.1:6006/v1/traces

Privacy

  • metadata-only is the default.
  • redacted-content exports redacted textual content.
  • full-content must be explicitly selected and may expose sensitive transcript data. Treat full-content carefully.

Historical timing

As this is a historical structural projection:

  • ATIF Step timestamps may be represented as observed timing.
  • Root boundaries may be derived from observed Step timestamps.
  • Where independent tool completion timing is unavailable from ATIF, the projection does not pretend to have measured runtime duration.

For implementation details, see docs/OBSERVABILITY.md. For the evidence model, ecosystem comparison, limitations, and external-review questions, see Reconstructing Agent Traces After the Fact Without Inventing Runtime Truth.

Migration from v0.1 ASEF output

v0.2 removes the proprietary ASEF schema. Existing *.asef.json files are not ATIF documents and must not be relabeled as such. Re-run the original source transcript through tfb import to produce a validated *.atif.json file, then review the TFB fidelity report. Python 3.11 is now the minimum supported version because the official ATIF models require it.

Contributing

Useful contributions include provider transcript fixtures, source adapters, target mappings for documented ingestion boundaries, fidelity-report improvements, and reproducible evidence about real cross-provider transformations. See CONTRIBUTING.md.

License

MIT License. See LICENSE.

Metadata

Release files for atomicdjt-trajectory-fidelity-bridge 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atomicdjt-trajectory-fidelity-bridge 0.5.0
File Size Uploaded Provenance Actions
atomicdjt_trajectory_fidelity_bridge-0.5.0.tar.gz 75.0 kB With provenance Details for atomicdjt_trajectory_fidelity_bridge-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for atomicdjt-trajectory-fidelity-bridge 0.5.0
File Interpreter ABI Platform Actions
atomicdjt_trajectory_fidelity_bridge-0.5.0-py3-none-any.whl Python 3 none any Details for atomicdjt_trajectory_fidelity_bridge-0.5.0-py3-none-any.whl

Total release size: 120.2 kB

Release files / atomicdjt_trajectory_fidelity_bridge-0.5.0.tar.gz

Download URL atomicdjt_trajectory_fidelity_bridge-0.5.0.tar.gz
Size 75.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e680addb3e1eb5a3a829a3bb5e639d42451a28e2c4211c0b46f2e224655f819b
BLAKE2b-256 checksum
How to use checksums
7de17dec98076dfe333dbf341e1f309734530da0e9758240a91585cffd13941b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / atomicdjt_trajectory_fidelity_bridge-0.5.0-py3-none-any.whl

Download URL atomicdjt_trajectory_fidelity_bridge-0.5.0-py3-none-any.whl
Size 45.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fe54cb43c924e3fc9fdcb46b794d8f61248ee06b049b3aa1c178bf27fc886312
BLAKE2b-256 checksum
How to use checksums
e3f26abfcd1e0a9aeae7a6a50cca88c2755680008cc8926ff397b82a216f0695
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for atomicdjt-trajectory-fidelity-bridge 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for atomicdjt_trajectory_fidelity_bridge-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page