JSONL Trajectory Protocol (ATIF-v1.6)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/headless/AGENTS.md
• packages/headless/README.md
• packages/headless/src/types.ts
• packages/headless/src/emit.ts
• packages/headless/src/runner.ts
• AGENTS.md

The JSONL Trajectory Protocol (ATIF-v1.6) is a structured specification for logging agent execution paths within the plugsuits ecosystem. It is primarily implemented in the @ai-sdk-tool/headless package to provide a non-interactive, machine-readable transcript of agent sessions. By emitting one JSON object per line (JSONL), the protocol enables seamless integration with CI/CD pipelines, automated benchmarks, and diagnostic tools.

This protocol ensures that every interaction—including user messages, agent reasoning, tool calls, and system observations—is captured with strict temporal and sequential integrity. It serves as the primary data exchange format for the project's headless runtime, allowing external consumers to reconstruct the agent's decision-making process without the overhead of a terminal UI.

Sources: packages/headless/AGENTS.md, packages/headless/README.md

Core Architecture and Design Principles

The ATIF-v1.6 specification is built around the concept of a "Trajectory," which is a linear sequence of events representing an agent's progress toward a goal.

Design Constraints

• Sequential Integrity: Every step event must include a step_id, which is a strictly increasing sequential integer starting from 1.
• Session Context: To reduce redundancy, the session_id is emitted exactly once in a MetadataEvent at the start of the stream, rather than being attached to every individual event.
• Observation Bundling: Tool results are not emitted as standalone events. Instead, they are bundled into the observation field of the subsequent AgentStepEvent or a dedicated SystemStepEvent.
• Metric Accuracy: Performance data (tokens, etc.) must come directly from the Vercel AI SDK stream.usage and should never be estimated.

Sources: packages/headless/AGENTS.md, packages/headless/src/types.ts

Data Flow and Emission

The runtime uses a centralized emitEvent function to write events to stdout. The flow typically begins with the initialization of a session via the SessionManager, followed by the execution of the agent loop within runHeadless.

Event Type Definitions

The protocol defines six primary event types that encapsulate the lifecycle and actions of an agent.

Event Type	Source	Role
metadata	System	Emitted once at session start; carries version and session info.
step	User/Agent/System	Represents a discrete turn in the conversation or a system observation.
compaction	System	Lifecycle annotation for history compaction events.
error	System	Indicates a fatal error or that iteration limits have been reached.

Sources: packages/headless/AGENTS.md, packages/headless/src/types.ts

Metadata Event

The MetadataEvent is the first line of any ATIF-v1.6 compliant log. It establishes the context for the entire trajectory.

{
  "type": "metadata",
  "timestamp": "2026-04-03T10:00:00.000Z",
  "session_id": "ses-abc123",
  "agent": {
    "name": "code-editing-agent",
    "version": "1.0.0",
    "model_name": "gpt-4o"
  }
}

Sources: packages/headless/AGENTS.md, packages/headless/README.md

Step Events

Step events are the core of the trajectory. They use a source field to distinguish between participants.

Agent Steps and Observations

When an agent performs an action, the AgentStepEvent includes tool_calls. The results of these calls (the "observations") are then provided in the next step.

Lifecycle and Compaction Events

Compaction events are used to signal when the conversation history has been summarized to save context window space. Unlike step events, these are lifecycle annotations and do not consume a step_id.

{
  "type": "compaction",
  "timestamp": "2026-04-03T10:00:11.200Z",
  "event": "complete",
  "tokensBefore": 45000,
  "tokensAfter": 12000,
  "strategy": "session-memory",
  "durationMs": 1200
}

Sources: packages/headless/AGENTS.md, packages/headless/src/types.ts

Implementation Details

The Headless Runner

The runHeadless function in packages/headless/src/runner.ts is responsible for orchestrating the loop and maintaining the sequential step_id counter. It accepts a HeadlessRunnerConfig which includes the agent's stream function and the message history.

Key Config Fields:

• maxIterations: A safety cap that, if exceeded, triggers an error event.
• onTodoReminder: A callback that allows the loop to continue if tasks remain in the TodoContinuation system.
• emitEvent: An optional custom sink; defaults to stdout.

Sources: packages/headless/README.md, packages/headless/src/runner.ts

Process Lifecycle and Signals

The protocol requires graceful shutdown to ensure the final state is captured. The registerSignalHandlers function manages SIGINT, SIGTERM, and other termination signals, mapping them to specific exit codes (e.g., SIGINT exits with 0, SIGTERM with 143).

Sources: packages/headless/src/signals.ts, packages/headless/README.md

Summary

The JSONL Trajectory Protocol (ATIF-v1.6) provides a robust framework for agent observability in the plugsuits project. By standardizing event structures and sequential identifiers, it enables precise auditing of agent behavior. The package @ai-sdk-tool/headless serves as the reference implementation, ensuring that tool interactions and context compactions are recorded with high fidelity for use in automated testing and performance benchmarking.