API Reference

This page describes the public API shipped in Agent Journal 1.10.1.

Coordinates

Artifact	Purpose	Java
`io.github.markpollack:journal-core:1.10.1`	Core domain, storage, evaluation, feedback, and traces	17+
`io.github.markpollack:claude-code-capture:1.10.1`	Claude Code capture	21+ runtime
`io.github.markpollack:gemini-cli-capture:1.10.1`	Gemini CLI capture	21+ runtime
`io.github.markpollack:grok-cli-capture:1.10.1`	Grok CLI capture	17+
`io.github.markpollack:codex-cli-capture:1.10.1`	Codex CLI capture	17+
`io.github.markpollack:antigravity-cli-capture:1.10.1`	Antigravity CLI capture	17+
`io.github.markpollack:junie-cli-capture:1.10.1`	Junie CLI capture	17+

`Journal`

Method	Result	Notes
`run(String experimentId)`	`RunBuilder`	Primary run factory
`experiment(String experimentId)`	`Experiment`	Gets or creates an experiment
`experiment(String id, Experiment.Builder builder)`	`Experiment`	Builder is ignored if the experiment already exists
`configure(JournalStorage storage)`	`void`	Call before creating runs
`storage()`	`JournalStorage`	Returns the global backend
`registerEventType(String, Class<? extends JournalEvent>)`	`void`	Registers an external subtype on the configured storage
`reset()`	`void`	Resets storage configuration and the experiment cache

`RunBuilder`

Method	Purpose
`name(String)`	Human-readable run name
`agent(String)`	Agent identifier
`task(String)`	Accepts a task identifier; 1.10.1 does not persist it or act on it
`repository(String)`	Accepts a repository path; 1.10.1 does not persist it or act on it
`config(Config)`	Replace the run configuration
`config(String, Object)`	Add one immutable input value
`tags(Tags)`	Replace tags
`tag(String, String)`	Add one tag
`previousRun(String)`	Link a retry to the prior run ID
`parentRun(String)`	Link a child run to a parent run ID
`start()`	Create a `RUNNING` `Run`

There is no config(Map) overload in 1.10.1. The task(String) and repository(String) setters are present, but the 1.10.1 run implementation does not consume either stored builder value.

`Run`

Area	Methods
Identity	`id()`, `name()`, `experiment()`, `agentId()`, `previousRunId()`, `parentRunId()`
Data	`config()`, `summary()`, `tags()`, `status()`
Execution	`logEvent(JournalEvent)`, `logMetric(...)`
Analysis	`logDerivedEvent(DerivedEvent)`
Artifacts	`logArtifact(String, String)`, `logArtifact(String, byte[], Map<String,Object>)`
Instruments	`metrics()`, `calls()`
Lifecycle	`setSummary(...)`, `fail(Throwable)`, `finish(RunStatus)`, `close()`

Event factories

JournalEvent is extensible. Built-in event records include timestamps and expose their Java type() value; file serialization uses the registered @type name.

Event	Common factory or builder
`LLMCallEvent`	`of(model, inputTokens, outputTokens, costUsd)`, `builder()`
`ToolCallEvent`	`success(tool, input, output, durationMs)`, `failure(tool, input, error, durationMs)`, `builder()`
`StateChangeEvent`	`of(from, to, reason)`
`MetricEvent`	`of(name, value, tags)`
`CustomEvent`	`of(name)`, `of(name, attributes)`
`GitPatchEvent`	`of(baseBranch, fileChanges)`
`GitCommitEvent`	`of(sha, message, branch)`
`GitBranchEvent`	`created(branchName, fromRef)`, `checkedOut(branchName)`, `deleted(branchName)`
`GitPullRequestEvent`	`created(...)`, `updated(...)`, `merged(...)`, `closed(...)`

Token, cost, and timing values

TokenUsage simple = TokenUsage.of(1200, 450);
TokenUsage withThinking = TokenUsage.of(1200, 450, 300);

TokenUsage allFields = new TokenUsage(
        1200, 450, 300, 200, 800, 0);

CostBreakdown cost = CostBreakdown.of(0.018, 0.00675);
TimingInfo timing = TimingInfo.of(2500, 2100, 400);

The 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.10.1.

`JournalStorage`

Area	Operations
Experiments	`saveExperiment`, `loadExperiment`, `listExperiments`, `experimentExists`
Runs	`saveRun`, `loadRun`, `listRuns`, `runExists`
Execution events	`appendEvent`, `loadEvents`
Derived events	`appendDerivedEvent`, `loadDerivedEvents`, `persistsDerivedEvents`
Feedback	`appendFeedback`, `loadFeedback`
Artifacts	`saveArtifact`, `loadArtifact`, `listArtifacts`
External event types	`registerEventSubtype`

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.

Evaluation API

EvalSubjectSources.fromJournal(storage, experimentId, runId) reads a run and produces subjects. EvalSubjectSources.fromEvents(events, runId) adapts an existing event list. EvalSubjectQuery supports:

Method	Purpose
`from(EvalSubjectSource)`	Start a query
`kind(EvalSubjectKind)`	Filter by kind
`where(Predicate<EvalSubject>)`	Add a predicate
`toSet()`	Materialize an `EvalSubjectSet`
`groupBy(Function)`	Group into subject sets
`countBy(Function)`	Count by classifier
`count()`	Count matches

Capture parsers

Claude Code

SessionLogParser.parse(response, phaseName, promptText)
SessionLogParser.parse(response, phaseName, promptText, traceFile)
SessionLogParser.parse(response, phaseName, promptText, traceFile, contentMode)
SessionLogParser.parse(response, phaseName, promptText, traceFile, contentMode, rawMode)
SessionLogParser.parse(response, phaseName, promptText, traceFile, contentMode, rawMode, maxTurns)

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. RunRecorder wraps an open Run, inherits recordPhase(PhaseCapture), exposes run() and lenient(), and owns finish()/close().

Gemini CLI

GeminiSessionParser.parse(result, phaseName, promptText)
GeminiSessionParser.parse(result, phaseName, promptText, traceFile)
GeminiSessionParser.parse(result, phaseName, promptText, traceFile, contentMode)

result is a Gemini SDK QueryResult. GeminiRunRecorder.recordPhase(GeminiPhaseCapture) records the core and derived projections.

Junie CLI

JunieSessionParser.parse(eventsFile, phaseName, promptText)
JunieSessionParser.parse(reader, phaseName, promptText)

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

JsonFileStorage does not validate path containment for caller-supplied identifiers or artifact names in 1.10.1.
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.

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

Coordinates

`Journal`

`RunBuilder`

`Run`

Event factories

Token, cost, and timing values

`JournalStorage`

Evaluation API

Capture parsers

Claude Code

Gemini CLI

Junie CLI

Storage cautions

​Coordinates

​Journal

​RunBuilder

​Run

​Event factories

​Token, cost, and timing values

​JournalStorage

​Evaluation API

​Capture parsers

​Claude Code

​Gemini CLI

​Junie CLI

​Storage cautions

Coordinates

`Journal`

`RunBuilder`

`Run`

Event factories

Token, cost, and timing values

`JournalStorage`

Evaluation API

Capture parsers

Claude Code

Gemini CLI

Junie CLI

Storage cautions