Skip to main content
On main, not yet released — 0.32.1-SNAPSHOT, checked against agent-client main 257f48d0. The lifecycle and recording API on this page is in the development snapshots built from main. None of it is in 0.32.0. Snapshot content changes as main moves, so name the main commit you built against.
Resolve 0.32.1-SNAPSHOT from the Central snapshot repository, with snapshots enabled:
See Using development snapshots from main for pinning one build and reading its provenance.

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 implement AgentExecutionProvider. 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:
A submit the session cannot take dispatches nothing and throws 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 executionTimeout is an execution deadline. It starts at acceptance, includes required advisors and setup, and excludes secondary recording. Reaching it fails the execution with FailureCode.TIMEOUT; it is not a cancellation.
  • cancel(false) and cancel(true) both stop only the selected turn; true also permits interrupting its worker.
  • A cancelled or failed result can be available before the provider process has stopped. awaitTermination(...) and termination() observe that separate fact. If cleanup cannot be confirmed by the cleanup deadline, the session is quarantined and later submits are refused CLEANUP_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 is Pending, Processing or Resubmitted, and bound the wait: a client with no recording configured reports NotConfigured, which never changes.
This code is from FailedExecutions.java, which the agent-client build compiles and runs offline (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-client main: