This page describes Agent Journal 1.11.0 (1.x). It does not apply to 2.0, the current line on main, which has a different format; see Which Journal do I need?.
Added or changed in 1.11.0
Migrating a caller from 1.10.1
Three kinds of compatibility apply, and they differ:- Constructors. Every earlier
PhaseCaptureandCodexPhaseCaptureconstructor is kept, so code that builds a capture with positional arguments compiles unchanged. A kept constructor fills the new components with empty values (no sub-agents, tracks unavailable, no session cost). - Record patterns. A record pattern names every component.
PhaseCapturegrew from 22 to 26 components (subagents,subagentTracksAvailable,reportedSubagentStats,sessionCostappended), andCodexPhaseCapturefrom 14 to 17 (subagents,subagentTracksAvailable,spawnedThreadIds). A pattern written against 1.10.1 does not compile against 1.11.0 until the new components are added. - JSON readers. A
PhaseCaptureserialised with Jackson has four more properties and aCodexPhaseCapturethree; readers that ignore unknown properties keep working. Journal files written by 1.11.0 load in 1.10.1 readers (no new record field, no new enum value), and 1.11.0 readers load older files.
Coordinates
Journal
RunBuilder
There is no
config(Map) overload in 1.11.0.
The task(String) and repository(String) setters are present, but the 1.11.0 run implementation does not consume either stored builder value.
Run
RunStatus is RUNNING, FINISHED, FAILED or CRASHED.
A run that finishes as failed or crashed records success=false.
A plain Run closed without finish(...) ends FINISHED; a Claude Code RunRecorder closed without finish() ends CRASHED since 1.11.0.
Event factories
JournalEvent is extensible.
Built-in event records include timestamps and expose their Java type() value; file serialization uses the registered @type name.
Token, cost, and timing values
TokenUsage constructor order is input, output, thinking, cache creation, cache read, and tool-use tokens.
There is no five-argument TokenUsage.of(...) overload in 1.11.0.
Thinking tokens are a subset of output tokens: total() is input plus output, cacheHitRatio() is cache reads divided by input plus cache reads, and effectiveInputTokens() is deprecated.
Input tokens exclude cache reads for every provider.
JournalStorage
JsonFileStorage implements every operation and reports durable derived-event persistence.
InMemoryStorage implements every operation in memory and reports the default non-durable derived-event behavior.
The header line of events.jsonl and analysis.jsonl carries schemaVersion (still 1), and since 1.11.0 producer and producerVersion; a header without producerVersion was written by 1.10.1 or earlier.
A file with a newer schema version than the reader knows, or a non-numeric one, is refused.
Event types registered with Journal.registerEventType are kept for the whole process and apply to storage configured later.
SourceRecordings
SourceRecordings.find(experimentId, sourceKind, sourceKey) looks a recorded execution up by the key its run carries in capture.sourceKind and capture.sourceKey; requireComplete fails on a recording that has not ended or ended with an error.
SourceRecordings.Outcome(runId, recordedNow) is what recordOnce returns.
Evaluation API
EvalSubjectSources.fromJournal(storage, experimentId, runId) reads a run and produces subjects.
EvalSubjectSources.fromEvents(events, runId) adapts an existing event list.
EvalSubjectQuery supports:
Capture parsers
Claude Code
response is the live Iterator<ParsedMessage> returned by the SDK; the parser does not read a session log file.
The maxTurns overload records the turn ceiling the caller launched the run with, because Claude Code does not report it back; pass SessionLogParser.UNKNOWN_MAX_TURNS (-1) when no ceiling was set. The shorter overloads pass -1.
The default content mode for trace-writing overloads is TRUNCATED; the default raw mode is NONE.
withSessionBaseline returns a copy of a later capture of the same session whose cost, per-model costs and API time are the difference from previous, with the running totals in sessionCost() and costBasis() set to session_delta; it never subtracts across session ids.
recordOnce records an execution at most once per experiment and storage root and returns a SourceRecordings.Outcome; configure is a UnaryOperator<RunBuilder> or null.
RunRecorder wraps an open Run, inherits recordPhase(PhaseCapture), exposes run() and lenient(), and owns finish()/close().
Only finish() records a completed run; close() without it records CRASHED.
A capture with sub-agents is written as one run per sub-agent, linked by parentRunId, tagged track=subagent; see Sub-agent Capture.
Gemini CLI
result is a Gemini SDK QueryResult.
GeminiRunRecorder.recordPhase(GeminiPhaseCapture) records the core and derived projections.
Codex CLI
rollouts is a CodexRollouts holding one CodexRollout(threadId, parentThreadId, sourcePath, lines) per thread, the root first; CodexRollouts.root() and children() expose them.
The single-file overloads are unchanged.
CodexRunRecorder.recordPhase(CodexPhaseCapture) records the core and derived projections; recordOnce is keyed by the root thread id.
Junie CLI
eventsFile is a Path to Junie’s session events.jsonl and reader is a BufferedReader over the same content; both throw IOException.
JunieRunRecorder.recordPhase(JuniePhaseCapture) records the core and derived projections.
Storage cautions
JsonFileStoragedoes not validate path containment for caller-supplied identifiers or artifact names in 1.11.0.- Use one writer per run and do not assume multi-process safety.
- File-backed load methods read the requested JSONL file into memory.
- Portable traces can contain sensitive content; see Capture SDK Sessions.