An interactive walkthrough of RFC 0004 for engineers familiar with ATIF 1.x: append-only event streaming (ATIF-E), consolidated trajectories (ATIF) and bundles (ATIF-B), unified tool actions, branch lineage, and lossless v1.x ↔ v2.0 migration.
v1.0–v1.8)ATIF evolved through nine minor versions from ATIF-v1.0 to ATIF-v1.8. Select a version on the right to see the fields it introduced.
extra="forbid"steps[] array, separate tool_calls and observation lists joined by ID, and untyped extra dicts. Supporting live streaming, non-linear execution, and cross-harness analytics required structural changes rather than additional optional fields.Using ATIF across 30+ agent harnesses and downstream consumers (NeMo, Phoenix, Letta, SkyRL) surfaced five structural limitations in the 1.x design.
ATIF 2.0 separates runtime event capture from analytical storage. Harnesses append events to an ATIF-E stream (.atif-e.jsonl), and a deterministic consolidation algorithm folds that stream into a single ATIF trajectory (.atif.json) or a multi-trajectory ATIF-B bundle (.atif-b.json).
schema_kind: File extensions distinguish the three formats on disk. Inside the payload, schema_kind: "event" | "trajectory" | "bundle" (alongside schema_version: "ATIF-v2.0") identifies the document when read from stdin, HTTP, PubSub, or a SQL JSON column, and serves as an O(1) discriminator for Pydantic, Zod, and JSON Schema validators.TrajectoryEvent EnvelopeEach line in an .atif-e.jsonl file has a shared envelope and exactly one payload key: trajectory, step, or action. Events record only the fields known at emit time; derived fields (step_id, final_metrics, union type discriminators) are omitted and computed during consolidation.
schema_kind | Always "event" on an ATIF-E line ("trajectory" / "bundle" on ATIF / ATIF-B roots). |
event_id | Unique within trajectory_id. Preserves the harness's native event ID (such as Claude Code's uuid). |
parent_event_id | Optional causal predecessor. Omitted on normal linear events (which implicitly link to the preceding event of the same trajectory_id); set explicitly when a branch or rewind jumps back to an earlier event. |
response_id | Provider inference ID. Events sharing a response_id always fold into the same Step. |
seq | Optional monotonic sequence number. |
In ATIF 1.x, a producer must either buffer the trajectory in memory until the run finishes or rewrite the entire JSON file after every step. ATIF-E appends one JSONL line per native event. Drag the slider to compare what is preserved if the container terminates mid-run.
trajectory.json on every turn causes quadratic I/O. Appending one JSONL line per event preserves partial runs on disk and supports live rollout streaming for online RL.TrajectoryEventA streaming adapter maps each native harness record directly to an ATIF-E event without buffering multi-event turns. Select a harness event type below and hover or click any field to inspect its mapping.
Using the example stream from RFC 0004 §6.5: after a user prompt, one streamed inference, and a tool output (ev-4), generation ev-5 is cancelled and replaced by a retry (ev-6) that branches from ev-4. Step through the three stages of Phase 1:
steps[], breaking causal ordering. In ATIF 2.0, the active trunk remains strictly linear while discarded branches are extracted as child Trajectory objects.Phase 2 folds each linear event chain using a three-state machine (IDLE → GENERATING → OBSERVED), an in-place actions_by_id pointer map, and a steps_by_response_id index. Step through the events below to watch the consolidated trajectory build.
Harnesses such as Claude Code emit a single API response across multiple JSONL records and repeat cumulative usage on each slice. Compare summing across slices vs. replacing with the latest snapshot:
msg_01XYZcontent, output)text parts (and unsigned, non-redacted reasoning parts with matching summarized) concatenate in place only when neither part has truncated_fields or extensions set. Signed or redacted thinking blocks stay separate.
schema_kind ("trajectory" / "bundle"), and type on every ContentPart and CanonicalAction (media type inferred from source.media_type).truncated_fields + optional BlobReference) on oversized fields not already truncated in ATIF-E.parent_step_id, ancestor_trajectory_ids, child_trajectory_ids, trajectory_depth, using an inverted index of event and action IDs.step_id numbered 1..N in fold order; when parent_steps_excluded is true, leading prefix steps unchanged from the parent are dropped (normally starting at parent_step_id + 1, or parent_step_id on a mid-step fork).CompactionInfo.step_id_start/end resolved from event IDs.status, if no { trajectory } event set it, from steps[-1].stop_reason: completed → completed, cancelled → cancelled, errored/timed_out/refused → failed, tools/max_tokens/unset (or no steps) → running.start_time, end_time, step_count, final_metrics (every step in this Trajectory, keeping explicit vendor totals; a bundle sums only native steps, original_trajectory_id == null).total_llm_calls counts each agent step with model content or metrics (one inference by construction) plus tool-internal Action.metrics.Trajectory Root Schema: 1.x vs. 2.0Select a category below to filter the schema diff, or click any field to see how it changed from ATIF 1.x.
session_id) vs. Path Identity (trajectory_id)ATIF v1.7 introduced separate session_id and trajectory_id fields, but both remained optional. In ATIF 2.0 both are required on every Trajectory, making (trajectory_id, step_id) a composite primary key across JSON, Protobuf, and SQL.
parent_trajectory_id | immediate parent | raw |
parent_reason | subagent · fork · rewind · retry · candidate · compaction · continuation | raw |
parent_event_id / parent_action_id | where it branched / which tool call spawned it | raw |
parent_steps_excluded | Delta Mode: untouched shared prefix steps omitted | raw |
parent_step_id | resolved step in parent | derived |
ancestor_trajectory_ids | root…parent, so SQL needs no recursive CTEs | derived |
trajectory_depth, child_trajectory_ids | tree helpers | derived |
Step Structure: ATIF 1.x vs. ATIF 2.0Step 2 from RFC 0001's GOOGL example (two parallel tool calls), converted to ATIF 2.0 via upgrade_v1_to_v2. Click the buttons below to highlight how each field group maps between versions.
Step.content[]Within a single LLM response, models frequently interleave signed or redacted thinking blocks, text responses, and parallel tool calls before any tool executes. Compare how ATIF 1.x and ATIF 2.0 represent a multi-block turn:
tool_calls and observation into Step.actions[]ATIF 1.x stores tool invocations in tool_calls[] and tool outputs in observation.results[], requiring consumers to join them by tool_call_id == source_call_id. ATIF 2.0 combines each invocation, its output, timing, and error state into a single Action object.
In ATIF 1.x, execution status, per-call timestamps, background task handles, and human approval decisions were stored in harness-specific extra keys (with 6 incompatible key names for tool errors alone). ATIF 2.0 defines typed fields for each:
Action.canonicalAction.name, arguments, and output always preserve the raw harness tool call. Action.canonical is an optional typed overlay that normalizes common operations across harnesses. Select an operation and a harness below:
canonical? SFT and replay pipelines need the exact tool name and argument schema emitted by the model, while cross-harness SQL queries need a consistent schema across harnesses. Storing Action.canonical as an optional overlay (a single-key oneof, optional MCP provenance in canonical.mcp, and a derived type) supports both without mutating the raw call.CanonicalAction VariantsSelect any variant below to view its typed fields and native tool mappings. Protobuf field tags are allocated in 10-tag blocks per family.
Suppose a user tries steps 4–5, rewinds to step 3, and continues with a new prompt for steps 4–6. Compare how ATIF 1.x, ATIF 2.0 Delta Mode, and ATIF 2.0 Self-Contained Mode represent the run:
TrajectoryBundleATIF v1.7 nested subagents recursively inside the parent trajectory. ATIF 2.0 flattens every linear path in a session (subagents, forks, Best-of-N candidates, compactions, and discarded rewind/retry branches) into TrajectoryBundle.trajectories[]:
parent_reason → prefix handling| Topology | reason | Prefix 1..K | First step_id |
|---|---|---|---|
| Root | — | n/a | 1 |
| Delegated subagent / compaction | subagent compaction | fresh context, or copied when context-forked | 1 |
| Rewind / 1-step retry | rewind retry | omitted in bundle (parent_steps_excluded: true) | K+1 (or K mid-step) |
| Best-of-N arm | candidate | omitted in bundle (parent_steps_excluded: true); winner merged back with original_trajectory_id | K+1 (or K mid-step) |
| Session fork | fork | copied by default (flag omitted) | 1 |
| Context continuation | continuation | from v1 is_copied_context | 1 |
Trajectory objects? Adding a separate branches[] structure would duplicate lineage metadata and require a 3-column (trajectory_id, branch_id, step_id) primary key in SQL. Modeling every linear path as a Trajectory keeps steps[] strictly linear everywhere.Step.compactionClaude Code (compact_boundary), Codex (compacted), OpenCode, Pi, and Terminus 2 all compact context during long runs. Compare the two ATIF 1.x patterns with ATIF 2.0's first-class Step.compaction:
Unbounded command outputs, file reads, and media produced 30–100+ MB trajectory files in 1.x, while ImageSource.path required a local filesystem. In ATIF 2.0, consolidation keeps an inline preview and records truncated_fields with an optional content-addressed BlobReference:
.atif-b.tar.zst layoutbundle.atif-b.json # root manifest, first entry events.atif-e.jsonl # optional raw ATIF-E stream blobs/sha256/4a/4a7c…e1 # <2-hex>/<64-hex>, raw bytes blobs/sha256/c0/c09f…2b
ATIF 1.x lacked structured fields for system instructions, skills, MCP servers, subagent definitions, OS/sandbox settings, and VCS state, so converters placed them under custom keys in agent.extra. Select a section below to inspect the ATIF 2.0 schema:
ATIF 2.0 retains the v1.2 inclusive invariant: input_tokens includes cached tokens, and output_tokens includes reasoning tokens. Because model providers report token buckets differently, Supplemental 0004-C specifies exact normalization formulas per provider:
| 1.x | 2.0 |
|---|---|
prompt_tokens | input_tokens |
completion_tokens | output_tokens |
cached_tokens | cache_read_tokens |
extra.{5 aliases} | cache_write_tokens new |
extra.reasoning_tokens … | reasoning_tokens new |
Step.llm_call_count | extensions["com.harborframework.v1"] moved (1 agent step = 1 LLM call) |
| — | cost_source, retry_count, time_to_first_token_ms, streaming_duration_ms, response_id, granular[] |
extensions and Promoted Core FieldsAcross 30 ATIF 1.x converters and integrations, identical concepts were stored under conflicting extra keys (5 names for cache-write tokens; 6 for tool errors). ATIF 2.0 promotes universal fields into the core schema and requires reverse-DNS or URL namespaces in extensions:
com.harborframework.* namespacescom.harborframework.evaluation | Trajectory / Bundle | reward, correct, verdict, benchmark, task_id, rollout_rank, breakdown… |
com.harborframework.rl | Trajectory + Step | prompt_id, group_index, masked_out · per step reward, done, policy_version, assistant_masks, env_tokens… |
com.harborframework.v1 | any container | schema_version, llm_call_count, message_was_string, continued_trajectory_ref, subagent_trajectory_ref, extra, tool_call_extra, observation_extra |
upgrade_v1_to_v2)upgrade_v1_to_v2 converts any ATIF v1.0–v1.8 document to v2.0, and downgrade_v2_to_v1(upgrade_v1_to_v2(doc)) preserves full semantic equivalence (with timestamps normalized to UTC RFC 3339) whenever extensions["com.harborframework.v1"] is retained. Select a rule below to highlight its effect on RFC 0001's GOOGL trajectory:
The TypeScript interfaces map 1:1 onto proto3 (using oneof for unions and string for open vocabularies) and onto a 4-table analytical SQL schema. Compare querying shell command failure rates and average cost by agent and model in ATIF 2.0 vs. ATIF 1.x:
trajectories, (trajectory_id, step_id) is unique across the warehouse, and excluding discarded branches requires only a filter on parent_reason.Overview of the six structural changes in ATIF 2.0 and practical checklists for trajectory producers and consumers.
.atif-e.jsonl): one schema_kind: "event" line per native event, with native IDs as event_id. Set parent_event_id only on a branch or rewind jump.response_id whenever the provider gives one. Leave out derived fields.canonical when you know the operation's meaning.truncated_fields (and optional blob). Media goes in source.Trajectory, Step, ContentPart, Action, or catalog items)..atif.json, or Harbor's trajectory.json; dispatch on schema_kind): steps is still a contiguous, linear 1..N.step.actions, not two arrays joined on IDs.original_trajectory_id == null (previously is_copied_context)..atif-b.json) for subagents and branches, and filter on parent_reason.canonical.type rather than per-harness tool-name lists.upgrade_v1_to_v2; nothing is lost.