feat: add LangGraph adapter with per-tool governance (#1243)

Add LangGraphAdapter class with builder pattern and AutoCloseable for
wrapping LangGraph workflows with AxonFlow governance gates. Provides
per-tool governance via checkToolGate()/toolCompleted() and MCP policy
enforcement via mcpToolInterceptor(). 12 source files, 47 tests.

Author: saurabhjain1592

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `LangGraphAdapter` class — wraps LangGraph workflows with AxonFlow governance gates and per-tool policy enforcement. Includes:
+  - `checkGate()` / `stepCompleted()` — step-level governance at LangGraph node boundaries
+  - `checkToolGate()` / `toolCompleted()` — per-tool governance within tool_call nodes (each tool gets its own gate check)
+  - `mcpToolInterceptor()` — factory returning an interceptor enforcing `mcpCheckInput → handler → mcpCheckOutput` around every MCP tool call
+  - `waitForApproval()` — poll until a step is approved or rejected
+  - `startWorkflow()` / `completeWorkflow()` / `abortWorkflow()` / `failWorkflow()` — workflow lifecycle management
+  - Builder pattern construction, implements `AutoCloseable`
+- `WorkflowBlockedError` and `WorkflowApprovalRequiredError` exception classes
+- Builder-based option classes: `CheckGateOptions`, `StepCompletedOptions`, `CheckToolGateOptions`, `ToolCompletedOptions`
+- MCP interceptor types: `MCPInterceptorOptions`, `MCPToolRequest`, `MCPToolHandler`, `MCPToolInterceptor`
+
+---
+
 ## [4.1.0] - 2026-03-14
 
 ### Added

pom.xml

@@ -178,6 +178,7 @@
                 <artifactId>maven-surefire-plugin</artifactId>
                 <version>${maven-surefire-plugin.version}</version>
                 <configuration>
+                    <argLine>@{argLine} -Dnet.bytebuddy.experimental=true</argLine>
                     <includes>
                         <include>**/*Test.java</include>
                     </includes>

src/main/java/com/getaxonflow/sdk/adapters/CheckGateOptions.java

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2026 AxonFlow
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.getaxonflow.sdk.adapters;
+
+import com.getaxonflow.sdk.types.workflow.WorkflowTypes.ToolContext;
+
+import java.util.Map;
+
+/**
+ * Options for {@link LangGraphAdapter#checkGate}.
+ */
+public final class CheckGateOptions {
+
+    private final String stepId;
+    private final Map<String, Object> stepInput;
+    private final String model;
+    private final String provider;
+    private final ToolContext toolContext;
+
+    private CheckGateOptions(Builder builder) {
+        this.stepId = builder.stepId;
+        this.stepInput = builder.stepInput;
+        this.model = builder.model;
+        this.provider = builder.provider;
+        this.toolContext = builder.toolContext;
+    }
+
+    public String getStepId() {
+        return stepId;
+    }
+
+    public Map<String, Object> getStepInput() {
+        return stepInput;
+    }
+
+    public String getModel() {
+        return model;
+    }
+
+    public String getProvider() {
+        return provider;
+    }
+
+    public ToolContext getToolContext() {
+        return toolContext;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static final class Builder {
+        private String stepId;
+        private Map<String, Object> stepInput;
+        private String model;
+        private String provider;
+        private ToolContext toolContext;
+
+        private Builder() {
+        }
+
+        public Builder stepId(String stepId) {
+            this.stepId = stepId;
+            return this;
+        }
+
+        public Builder stepInput(Map<String, Object> stepInput) {
+            this.stepInput = stepInput;
+            return this;
+        }
+
+        public Builder model(String model) {
+            this.model = model;
+            return this;
+        }
+
+        public Builder provider(String provider) {
+            this.provider = provider;
+            return this;
+        }
+
+        public Builder toolContext(ToolContext toolContext) {
+            this.toolContext = toolContext;
+            return this;
+        }
+
+        public CheckGateOptions build() {
+            return new CheckGateOptions(this);
+        }
+    }
+}

src/main/java/com/getaxonflow/sdk/adapters/CheckToolGateOptions.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 AxonFlow
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.getaxonflow.sdk.adapters;
+
+import java.util.Map;
+
+/**
+ * Options for {@link LangGraphAdapter#checkToolGate}.
+ */
+public final class CheckToolGateOptions {
+
+    private final String stepName;
+    private final String stepId;
+    private final Map<String, Object> toolInput;
+    private final String model;
+    private final String provider;
+
+    private CheckToolGateOptions(Builder builder) {
+        this.stepName = builder.stepName;
+        this.stepId = builder.stepId;
+        this.toolInput = builder.toolInput;
+        this.model = builder.model;
+        this.provider = builder.provider;
+    }
+
+    public String getStepName() {
+        return stepName;
+    }
+
+    public String getStepId() {
+        return stepId;
+    }
+
+    public Map<String, Object> getToolInput() {
+        return toolInput;
+    }
+
+    public String getModel() {
+        return model;
+    }
+
+    public String getProvider() {
+        return provider;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static final class Builder {
+        private String stepName;
+        private String stepId;
+        private Map<String, Object> toolInput;
+        private String model;
+        private String provider;
+
+        private Builder() {
+        }
+
+        public Builder stepName(String stepName) {
+            this.stepName = stepName;
+            return this;
+        }
+
+        public Builder stepId(String stepId) {
+            this.stepId = stepId;
+            return this;
+        }
+
+        public Builder toolInput(Map<String, Object> toolInput) {
+            this.toolInput = toolInput;
+            return this;
+        }
+
+        public Builder model(String model) {
+            this.model = model;
+            return this;
+        }
+
+        public Builder provider(String provider) {
+            this.provider = provider;
+            return this;
+        }
+
+        public CheckToolGateOptions build() {
+            return new CheckToolGateOptions(this);
+        }
+    }
+}