# Agent Trajectory Interchange Format (ATIF)

VT Code implements the [Agent Trajectory Interchange Format (ATIF)](https://www.harborframework.com/docs/agents/trajectory-format) v1.4, a standardized JSON-based specification for logging complete agent interaction histories. ATIF trajectories are usable across debugging, visualization, Supervised Fine-Tuning (SFT), and Reinforcement Learning (RL) pipelines.

For the full specification, see the [ATIF RFC](https://github.com/laude-institute/harbor/blob/main/docs/rfcs/0001-trajectory-format.md).

## Overview

When enabled, VT Code exports an `atif-trajectory.json` file alongside the existing `.jsonl` trajectory log at session end. The file captures the complete session: user messages, agent responses, tool executions, observations, and per-step/aggregate LLM metrics.

## Configuration

Enable ATIF export in `vtcode.toml`:

```toml
[telemetry]
atif_enabled = true
```

The ATIF export is independent of `trajectory_enabled` — you can enable one without the other.

Output location: `~/.vtcode/sessions/atif-trajectory-<session-id>-<timestamp>.json`

## Schema

ATIF v1.4 defines these core types:

### Root-Level Trajectory

| Field | Type | Status | Description |
|-------|------|--------|-------------|
| `schema_version` | String | Required | `"ATIF-v1.4"` |
| `session_id` | String | Required | Unique identifier for the agent run |
| `agent` | Object | Required | Agent configuration (name, version, model) |
| `steps` | Array | Required | Ordered interaction steps |
| `notes` | String | Optional | Developer notes |
| `final_metrics` | Object | Optional | Aggregate metrics for the full trajectory |
| `extra` | Object | Optional | Custom root-level metadata |

### Step Object

| Field | Type | Status | Description |
|-------|------|--------|-------------|
| `step_id` | Integer | Required | Ordinal index (starting from 1) |
| `timestamp` | String | Optional | ISO 8601 timestamp |
| `source` | String | Required | `"system"`, `"user"`, or `"agent"` |
| `model_name` | String | Optional | LLM model used (agent steps only) |
| `message` | String | Required | Step content |
| `reasoning_content` | String | Optional | Agent internal reasoning |
| `tool_calls` | Array | Optional | Tool/function invocations |
| `observation` | Object | Optional | Environment feedback |
| `metrics` | Object | Optional | Per-step LLM metrics |
| `extra` | Object | Optional | Custom step-level metadata |

### Metrics

| Field | Type | Description |
|-------|------|-------------|
| `prompt_tokens` | Integer | Total input tokens (cached + non-cached) |
| `completion_tokens` | Integer | Tokens generated by the model |
| `cached_tokens` | Integer | Subset of prompt_tokens that were cache hits |
| `cost_usd` | Float | Estimated cost for this step |
| `logprobs` | Array | Log probabilities for RL training |
| `completion_token_ids` | Array | Token IDs for RL training |
| `prompt_token_ids` | Array | Input token IDs |

### Final Metrics

| Field | Type | Description |
|-------|------|-------------|
| `total_prompt_tokens` | Integer | Sum of all prompt tokens |
| `total_completion_tokens` | Integer | Sum of all completion tokens |
| `total_cached_tokens` | Integer | Sum of all cached tokens |
| `total_cost_usd` | Float | Total estimated cost |
| `total_steps` | Integer | Total number of steps |

## VT Code Event Mapping

VT Code converts its internal `ThreadEvent` stream to ATIF steps:

| VT Code Event | ATIF Source | Notes |
|--------------|-------------|-------|
| `AgentMessage` | `agent` | Agent text response |
| `Plan` | `agent` | Plan mode content |
| `Reasoning` | `agent` | Model reasoning/thinking |
| `ToolInvocation` + `ToolOutput` | `agent` | Paired into single step with tool_calls + observation |
| `CommandExecution` | `agent` | Shell command with output |
| `McpToolCall` | `agent` | MCP tool invocation |
| `TurnCompleted` | `system` | Turn boundary with usage metrics |
| `TurnFailed` | `system` | Failed turn with error message |
| `FileChange` | `system` | File modification summary |
| `WebSearch` | `system` | Search query and results |
| `Harness` | `system` | Continuation/verification events |
| `CompactBoundary` | `system` | Context compaction event |

Lifecycle events (`TurnStarted`, `ItemStarted`, `ItemUpdated`, `PlanDelta`) are skipped — only terminal states are exported.

## Implementation

The ATIF implementation lives in `vtcode-exec-events/src/atif.rs` with:

- **Schema types**: `Trajectory`, `AtifAgent`, `Step`, `AtifToolCall`, `Observation`, `ObservationResult`, `StepMetrics`, `FinalMetrics`
- **`AtifTrajectoryBuilder`**: Stateful collector that converts live `ThreadEvent` streams into ATIF trajectories. Implements `EventEmitter` for direct integration with the event pipeline.
- **Tool call pairing**: `ToolInvocation` events are buffered until matching `ToolOutput` arrives, then merged into a single ATIF step with both `tool_calls` and `observation`.

### Rust Usage

```rust
use vtcode_exec_events::atif::*;

// Create builder
let agent = AtifAgent::vtcode().with_model("gemini-2.5-flash");
let mut builder = AtifTrajectoryBuilder::new(agent);

// Feed ThreadEvents as they arrive
builder.process_event(&thread_event);

// Finalize
let trajectory = builder.finish(None);
let json = serde_json::to_string_pretty(&trajectory)?;
```

## Example Output

```json
{
  "schema_version": "ATIF-v1.4",
  "session_id": "session-abc123",
  "agent": {
    "name": "vtcode",
    "version": "0.96.15",
    "model_name": "gemini-2.5-flash"
  },
  "steps": [
    {
      "step_id": 1,
      "timestamp": "2025-04-05T10:30:00Z",
      "source": "agent",
      "message": "I'll read the file for you."
    },
    {
      "step_id": 2,
      "timestamp": "2025-04-05T10:30:02Z",
      "source": "agent",
      "tool_calls": [
        {
          "tool_call_id": "tc_0",
          "function_name": "read_file",
          "arguments": { "path": "src/main.rs" }
        }
      ],
      "observation": {
        "results": [
          {
            "source_call_id": "tc_0",
            "content": "fn main() { println!(\"Hello\"); }"
          }
        ]
      }
    },
    {
      "step_id": 3,
      "timestamp": "2025-04-05T10:30:05Z",
      "source": "system",
      "message": "turn_completed",
      "metrics": {
        "prompt_tokens": 520,
        "completion_tokens": 80,
        "cached_tokens": 100
      }
    }
  ],
  "final_metrics": {
    "total_prompt_tokens": 520,
    "total_completion_tokens": 80,
    "total_cached_tokens": 100,
    "total_steps": 3
  }
}
```

## Schema Versions

| Version | Changes |
|---------|---------|
| **ATIF-v1.4** (current) | Added `prompt_token_ids` for prompt token analysis |
| ATIF-v1.3 | Added `completion_token_ids` for RL training |
| ATIF-v1.2 | Extended observation to support system steps |
| ATIF-v1.1 | Added `extra` field at root level |
| ATIF-v1.0 | Initial specification |

## Interoperability

VT Code's ATIF trajectories are compatible with:

- [Harbor](https://www.harborframework.com/) evaluation framework and trajectory validator
- Any tool consuming ATIF-compliant JSON (debugging, visualization, SFT/RL pipelines)
- Other ATIF-producing agents: OpenHands, Mini-SWE-Agent, Gemini CLI, Claude Code, Codex

## Related Resources

- [ATIF RFC Specification](https://github.com/laude-institute/harbor/blob/main/docs/rfcs/0001-trajectory-format.md)
- [Harbor Framework Documentation](https://www.harborframework.com/docs/agents/trajectory-format)
- [Real-world trajectory examples](https://github.com/laude-institute/harbor/tree/main/tests/golden)
- [VT Code Architecture](../ARCHITECTURE.md)
