Release 6.1.0

AxonFlow Java SDK v6.1.0

Installation (Maven)

<dependency>
  <groupId>com.axonflow</groupId>
  <artifactId>axonflow-java-sdk</artifactId>
  <version>6.1.0</version>
</dependency>

Minor release. Surfaces fields the AxonFlow agent has emitted since v7.1.0 (Plugin Batch 1) but the SDK didn't declare. Pure field-additions on existing methods — additive only, no breaking changes. The pre-existing constructors are preserved as source-compat overloads. Documented in OpenAPI via platform v7.4.3.

Coordinated cycle: TypeScript v6.1.0 / Python v6.8.0 / Go v5.8.0 ship same day with the same field set.

Added

• MCPCheckInputResponse gains 5 optional Plugin Batch 1 fields:
  • decisionId: String — audit correlator
  • riskLevel: String — low | medium | high | critical
  • policyMatches: List<ExplainPolicy> — per-policy explainability records
  • overrideAvailable: Boolean — whether session override is permitted for the matched policies (boxed so callers can distinguish "unset" from false on older platforms)
  • overrideExistingId: String — already-active override consumed by this decision (if any)
• MCPCheckOutputResponse gains 3 optional fields:
  • decisionId: String
  • policyMatches: List<ExplainPolicy>
  • redactedMessage: String — text-redaction counterpart to redactedData (used when the connector returned a string message rather than tabular rows; e.g. execute-style responses)

ExplainPolicy already shipped — same Jackson-annotated record now reused on the MCP response types. Pre-v7.1.0 platforms leave all new fields as null; callers should treat null as "context not available" rather than an error.

Source compatibility

Both MCPCheckInputResponse and MCPCheckOutputResponse retain their v6.0.0 constructor signatures as overloads that delegate to the new @JsonCreator constructors with null for the new fields. Existing callers that build response instances locally compile unchanged. equals() / hashCode() / toString() updated to include the new fields.

Deferred

client.explainDecision(decisionId) and the full ExplainRule / DecisionExplanation type surface are tracked separately as feature work. This release ships only field-surfacing on existing methods.

Release 6.0.0

AxonFlow Java SDK v6.0.0

Installation (Maven)

<dependency>
  <groupId>com.axonflow</groupId>
  <artifactId>axonflow-java-sdk</artifactId>
  <version>6.0.0</version>
</dependency>

This is a major release. The bump is driven by a single observable-contract change: WebhookSubscription.equals() and .hashCode() now compare on id only, not every field. Coordinated with the TypeScript SDK v6.0.0 release (PolicyInfo rename) as a v6 alignment cycle for the SDKs that needed breaking changes; Python (v6.7.0) and Go (v5.7.0) ship as minor on the same day because their changes are purely additive.

BREAKING — WebhookSubscription equality is now identity-based on id

WebhookSubscription is an entity, not a value object. Two instances with the same id represent the same logical webhook regardless of whether one view has loaded secret (only returned by createWebhook) and another has not, or whether updatedAt / active have moved between fetches.

Previously equals() / hashCode() compared every field. That meant a webhook constructed locally with the legacy 6-arg constructor compared unequal to the same logical webhook deserialized from a server response that included secret / tenantId / orgId. Set<WebhookSubscription>, Map keying, and identity-tracking caches all broke under those semantics.

Identity-based equality is the canonical entity semantics; the prior value-based equality was a bug. Because equals() / hashCode() are part of the observable Java contract that callers depend on for set deduplication, map lookup, and identity caches, the fix is a breaking change per strict semver — even though the new behaviour corrects incorrect semantics rather than introducing them.

If you need content-equality (e.g. to detect a rotated secret), compare the relevant getters directly. The 6-arg constructor is preserved as a source-compat overload for callers building local instances; only equals() / hashCode() semantics changed. toString() is unchanged (still emits full state with secret redacted).

Added

• Version alignment check (.github/workflows/validate-version-alignment.yml). CI now fails any PR or push to main where pom.xml's <version> drifts from the first released ## [X.Y.Z] section in CHANGELOG.md. Matches the pattern in the platform repo and the Go SDK.
• Wire-shape contract gate (.github/workflows/wire-shape-contract.yml). CI fails any PR that introduces drift between Java @JsonProperty annotations and the OpenAPI specs pinned at tests/fixtures/wire-shape-baseline.json::openapi_specs_sha. Four gates: cross-spec schema divergence, intra-file schema duplicates, per-type SDK-vs-spec drift, and registered-type rename-escape. The pinned spec SHA is itself guarded by a spec-pin-bump PR label so a single PR can't both move the SHA and silence drift. Source-discovery walks brace depth so nested classes (e.g. WorkflowTypes.CreateWorkflowRequest) and inner enums are attributed to the correct type rather than the file's outer class. Mirrors the Python, Go, and TypeScript gates.
• WebhookSubscription.secret — HMAC-SHA256 signing key now exposed on the response from createWebhook. Required to verify the X-AxonFlow-Signature header on inbound webhook deliveries; without it, callers can't validate payload authenticity. Also adds tenantId and orgId (ownership scoping). The 6-arg constructor is preserved as a source-compat overload that delegates to the 9-arg with nulls for the new fields. toString() redacts secret to avoid log leakage.
• BudgetAlert.acknowledged — alert dismissal flag. Also adds @JsonProperty annotations on previously-unannotated fields (id, threshold, message) so the wire-shape gate can see them; Jackson's default name mapping was correct, but the validator's discovery walks @JsonProperty only.

Fixed

• Telemetry pings now deliver reliably from short-lived JVMs (CLI, serverless, cold-starts). AxonFlow construction blocks briefly while the ping is sent synchronously (bounded by the telemetry timeout).
• Telemetry path is bounded at TIMEOUT_SECONDS (3s) total; the /health probe and checkpoint POST share a single monotonic deadline instead of stacking independent timeouts.

Release 5.7.0

AxonFlow Java SDK v5.7.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.7.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.7.0'

Added

• Rich ApproveStepResponse / RejectStepResponse — both classes now carry
  the same shape as the step-gate response: decision resolves to "allow" or
  "block", retryContext mirrors the gate response retry state, approvedBy
  / approvedAt / rejectedBy / rejectedAt carry reviewer identity,
  approvalId is the deterministic HITL queue UUID, policiesMatched
  reconstructs the governance trail. The legacy workflowId / stepId /
  status fields remain for back-compat.
• planId on approve/reject responses — populated when the response comes
  from the MAP plan-scoped endpoint; empty on WCP plane responses. Same types
  work across both endpoints.
• Back-compat 3-arg constructors — new ApproveStepResponse(workflowId, stepId, status)
  and new RejectStepResponse(workflowId, stepId, status) still compile, so
  existing test fixtures and SDK consumers keep working without changes.
• getPendingPlanApprovals / getPendingPlanApprovalsAsync — new client
  methods that list MAP-plane pending approvals
  (GET /api/v1/plans/approvals/pending), the counterpart of
  getPendingApprovals for the WCP plane. The two-arg form accepts an
  optional planId filter so reviewer tools can scope the listing to one
  plan. Available on Evaluation+ licenses (same tier gate as the MAP step
  approve/reject endpoints).
• PendingApproval.planId — populated on MAP-plane entries, null on
  WCP-plane entries. Mirrors the approve/reject asymmetry. PendingApproval
  also gains stepIndex, decision, decisionReason, and approvalStatus
  so reviewer tools can render the full approval context without a second
  request. The existing 6-arg back-compat constructor still works; new
  fields default to null / 0 for callers that don't pass them.

Fixed

• approveStep / rejectStep / getPendingApprovals endpoint URLs —
  all three previously targeted non-existent paths under
  /api/v1/workflow-control/ and would fail against a real AxonFlow server.
  Corrected to the canonical /api/v1/workflows/{id}/steps/{step_id}/(approve|reject)
  and /api/v1/workflows/approvals/pending routes. Customers using these
  methods against a live deployment were receiving 404s; this release makes
  them work.
• PendingApprovalsResponse getters and JSON field names aligned with the
  wire shape — the class previously declared getApprovals() / getTotal()
  over a JSON body with keys approvals / total, which never matched the
  server (pending_approvals / count). Getters renamed to
  getPendingApprovals() / getCount() with the correct JSON bindings.
  Callers that read response.getApprovals() or response.getTotal() need
  to update to the new getter names.

Deprecated

• DO_NOT_TRACK=1 as an AxonFlow telemetry opt-out — scheduled for removal after 2026-05-05 in the next major release. Use AXONFLOW_TELEMETRY=off instead. The SDK emits a one-line migration warning when DO_NOT_TRACK=1 is the active control and AXONFLOW_TELEMETRY=off is not also set.

Unchanged

• approveStep(workflowId, stepId) / rejectStep(workflowId, stepId, reason)
  method signatures on AxonFlow are unchanged — only the response fields grew.

Release 5.6.0

AxonFlow Java SDK v5.6.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.6.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.6.0'

Added

• retry_context and idempotency_key support on the step gate —
  StepGateResponse now carries a RetryContext object on every gate call with the
  true (workflow_id, step_id) lifecycle: gateCount, completionCount,
  priorCompletionStatus (PriorCompletionStatus enum —
  NONE / COMPLETED / GATED_NOT_COMPLETED), priorOutputAvailable,
  priorOutput, priorCompletionAt, firstAttemptAt, lastAttemptAt,
  lastDecision, and idempotencyKey. Prefer these to the legacy cached /
  decisionSource fields.
• stepGate(workflowId, stepId, request, options) overload — new 4-arg overload
  taking StepGateOptions. Use StepGateOptions.includePriorOutput() to send
  ?include_prior_output=true so retryContext.priorOutput is populated when a prior
  /complete has landed. Existing 3-arg overload keeps its signature and delegates
  with StepGateOptions.defaults().
• StepGateRequest.idempotencyKey — caller-supplied opaque business-level key
  (max 255 chars; validated at construction). Immutable once recorded on the first gate
  call for a (workflow, step); subsequent gate/complete calls must pass the same key.
• MarkStepCompletedRequest.idempotencyKey — must match the key set on the
  corresponding gate call, if any. Mismatch (including missing-vs-set on either side)
  surfaces as a typed IdempotencyKeyMismatchException.
• IdempotencyKeyMismatchException — new typed exception in
  com.getaxonflow.sdk.exceptions. Thrown by stepGate and markStepCompleted when
  the platform returns HTTP 409 with error.code == "IDEMPOTENCY_KEY_MISMATCH".
  Surfaces workflowId, stepId, expectedIdempotencyKey, receivedIdempotencyKey,
  plus inherited statusCode=409 and errorCode="IDEMPOTENCY_KEY_MISMATCH".
• RetryContext, PriorCompletionStatus, StepGateOptions — exported in
  WorkflowTypes.

Fixed

• 409 dispatch on step gate/complete — previously all 409 responses on
  markStepCompleted fell through to a generic AxonFlowException(..., 409, "VERSION_CONFLICT"), conflating step idempotency conflicts with plan version
  conflicts. The step gate/complete call sites now inspect the 409 body and dispatch
  to IdempotencyKeyMismatchException when error.code matches, falling back to a
  generic AxonFlowException otherwise. Plan update paths (which also use 409) are
  untouched.

Deprecated

• StepGateResponse.isCached() and StepGateResponse.getDecisionSource() —
  marked @Deprecated. Use getRetryContext().getGateCount() > 1 and
  getRetryContext().getPriorCompletionStatus() instead. Planned for removal in a
  future major version.

Compatibility

Companion to the platform change that introduces retry_context on
POST /api/v1/workflows/{workflow_id}/steps/{step_id}/gate. Additive only — existing
callers that never set idempotencyKey or pass StepGateOptions see no behavior
change. Binary-compatibility preserved: old StepGateRequest, StepGateResponse, and
MarkStepCompletedRequest constructors kept alongside new ones.

Release 5.5.0

AxonFlow Java SDK v5.5.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.5.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.5.0'

Added

• mapTimeout field on AxonFlowConfig — brings Java to parity with
  the TypeScript, Python, and Go SDKs (all three already had a separate
  MAP timeout). The shared timeout (default 60s) only covered single-
  request endpoints; MAP plans routinely take 60-120s because they
  chain multiple LLM calls end-to-end, and the global timeout was
  cutting them off. New constant DEFAULT_MAP_TIMEOUT = 120s, new
  builder method AxonFlowConfig.builder().mapTimeout(Duration.ofSeconds(300)),
  and new environment variable AXONFLOW_MAP_TIMEOUT_SECONDS. All
  plan-lifecycle methods (generatePlan, executePlan, getPlanStatus,
  updatePlan, cancelPlan, resumePlan, rollbackPlan,
  getPlanVersions) now use a plan-specific OkHttpClient clone with
  callTimeout / readTimeout / writeTimeout set to mapTimeout.
  Shares connection pool + interceptors + dispatcher with the main
  client; only the timeout attributes differ. Keep mapTimeout ≤
  server AXONFLOW_MAP_MAX_TIMEOUT_SECONDS (default 300s) ≤
  front-door ALB idle_timeout.timeout_seconds (default 300s), or the
  connection is killed mid-stream.

Release 5.4.0

AxonFlow Java SDK v5.4.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.4.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.4.0'

Changes

See CHANGELOG.md for details.

Release 5.3.0

AxonFlow Java SDK v5.3.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.3.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.3.0'

Changes

See CHANGELOG.md for details.

Release 5.2.0

AxonFlow Java SDK v5.2.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.2.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.2.0'

Changes

See CHANGELOG.md for details.

Release 5.1.0

AxonFlow Java SDK v5.1.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.1.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.1.0'

Changes

See CHANGELOG.md for details.

Release 5.0.0

AxonFlow Java SDK v5.0.0

Installation

Maven:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.0.0</version>
</dependency>

Gradle:

implementation 'com.getaxonflow:axonflow-sdk:5.0.0'

Changes

See CHANGELOG.md for details.