Add the snapshot repository
Add the snapshot repository
Resolve See Using development snapshots from main for pinning one build and reading its provenance.
0.32.1-SNAPSHOT from the Central snapshot repository, with snapshots enabled:Overview
The lifecycle API runs a goal asynchronously and keeps the execution, its termination and its recording as separate facts. It is available to providers that implementAgentExecutionProvider. The new modules, none of them on Maven Central at 0.32.0:
A legacy
AgentApi still supports its existing blocking path; runAsync() and retained Client sessions reject it explicitly.
A one-shot call
client.goal(...).runAsync() returns at once with an AgentExecution:
The Client runs each execution on its own virtual thread; there is no executor to configure.
A retained session
client.sessions().create(...) opens a retained AgentSession. Turns on one session run one at a time and share its history:
AgentOperationException. Its failure() is BUSY while a turn still holds the session (including a cancelled or failed one whose work has not settled), CLEANUP_UNKNOWN once the session is quarantined, or CLOSED once it is closing. AgentOperationException extends IllegalStateException, so existing catches still work. The shared conversation tutorial maps these to HTTP statuses.
Cancellation, caller timeouts and execution timeouts
result(Duration)is a caller timeout. Neither it nor an interrupt stops the execution; the caller just stops waiting.- A positive
executionTimeoutis an execution deadline. It starts at acceptance, includes required advisors and setup, and excludes secondary recording. Reaching it fails the execution withFailureCode.TIMEOUT; it is not a cancellation. cancel(false)andcancel(true)both stop only the selected turn;truealso permits interrupting its worker.- A cancelled or failed result can be available before the provider process has stopped.
awaitTermination(...)andtermination()observe that separate fact. If cleanup cannot be confirmed by the cleanup deadline, the session is quarantined and later submits are refusedCLEANUP_UNKNOWN.
Recording outcomes
execution.recording() reports native recording separately from the result, and recording never changes the result. With agent-client-journal, nativeRecording() reports one of four outcomes:
Every outcome archives the call, linked by its decision. The evidence-only outcomes carry a
missing entry naming the profile or verdict.
Claude Code and Codex CLI versions are recorded, not gated: the Client accepts any Claude Code version on the SDK route and any Codex CLI version on the exec route. The observed version names the acquisition profile (claude-code-<version>-sdk-stdio-session-file, codex-cli-<version>-exec-stdio-rollout). With Agent Journal 2.0.0-SNAPSHOT, qualified one-shots are delivered under client-terminal-claude-sdk/1 and client-terminal-codex-exec/1.
Failed executions and fullRecord()
A failed result() throws AgentExecutionException. Its cause chain and detached failure() (FailureInfo: code, exception class, message, causes) carry the original failure, unchanged by recording.
Once the recording lane has sealed the provider’s native capture, execution.recording().evidence().fullRecord() returns a CaptureRecordReference naming the sealed manifest: its uri, its format (the acquisition profile) and its sha256. It is present also when the execution failed and when Journal did not qualify the sources. For Codex the manifest holds argv, exit status, observed processes and the original stdin, stdout and stderr. It is diagnostic evidence, not Journal qualification: nativeRecording() reports qualification.
Close order
The recording lane runs after the result, so close the client only after the recording has settled. A client closed earlier rejects the pending recording work and seals nothing. Wait only while delivery isPending, Processing or Resubmitted, and bound the wait: a client with no recording configured reports NotConfigured, which never changes.
FailedExecutionsTest).
Session and Client close() wait within one cleanup budget (default 10 seconds). Unconfirmed cleanup throws CleanupUnconfirmedException, which keeps the unconfirmed resources and a read-only cleanup handle.
Breaking on main: legacy Claude derived tracing removed
0.32.1-SNAPSHOT removes the legacy Claude trace-file surface: the builder options traceDir, traceContentMode and archiveTranscript; the provider fields phaseCapture, tracePath, transcriptPath and the derived token fields; and the properties agent-client.claude.trace-dir, trace-content-mode and archive-transcript. agent-claude no longer depends on Journal 1.x. Use ClaudeAgentModel.Builder.capture(ClaudeCaptureOptions) for blocking calls and ClaudeClientProvider.Builder.acquisitionDirectory(...) for lifecycle sessions. AgentClientResponse.getPhaseCapture() stays; for Claude it returns null. See legacy tracing removed.
Sources
All on agent-clientmain:
- Async result lifecycle, including “Failed executions and closing”
- Async capabilities and migration: what each provider supports and what remains to qualify
- Claude native guide and Codex one-shot and retained lifecycle
- Codex installed archive