Trajectory Fidelity Bridge
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.
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-onlyis the default.redacted-contentexports redacted textual content.full-contentmust be explicitly selected and may expose sensitive transcript data. Treatfull-contentcarefully.
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| atomicdjt_trajectory_fidelity_bridge-0.5.1.tar.gz | 75.2 kB | With provenance | Details for atomicdjt_trajectory_fidelity_bridge-0.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| atomicdjt_trajectory_fidelity_bridge-0.5.1-py3-none-any.whl | Python 3 | none | any | Details for atomicdjt_trajectory_fidelity_bridge-0.5.1-py3-none-any.whl |
Total release size: 120.4 kB
Release files / atomicdjt_trajectory_fidelity_bridge-0.5.1.tar.gz
| Download URL | atomicdjt_trajectory_fidelity_bridge-0.5.1.tar.gz |
|---|---|
| Size | 75.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb8478fb8e8a883d64f2cf6d9a961b77755fc0946b4c151c5a2751a67c5888db
|
|
BLAKE2b-256 checksum How to use checksums |
62e800f16b4f79dd80ab4e918eb2b935b918e4475fc76a65c64d6858d644b163
|
| 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 logRelease files / atomicdjt_trajectory_fidelity_bridge-0.5.1-py3-none-any.whl
| Download URL | atomicdjt_trajectory_fidelity_bridge-0.5.1-py3-none-any.whl |
|---|---|
| Size | 45.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f0b02b2bbe8a3f7989ec7ca0a4a88e72167a3b83bc968008c5b7dc12acb1ea34
|
|
BLAKE2b-256 checksum How to use checksums |
8a2513812426fa68549d80129abd237cab2674225511dbb85f2e63b610d2e228
|
| 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 logSecurity for atomicdjt-trajectory-fidelity-bridge 0.5.1
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.
Attestation for atomicdjt_trajectory_fidelity_bridge-0.5.1.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 logA 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.