fix: telemetry fixes, auditToolCall method (#111)

* fix: derive SDK version from pom.properties and detect platform version in telemetry

- Read SDK_VERSION from Maven pom.properties at runtime instead of
  hardcoded constant to prevent version drift between pom.xml and
  telemetry payload
- Detect platform version by calling /health endpoint before sending
  telemetry ping (2s timeout, silent failure)

* fix: use imported JsonNode instead of fully-qualified names

* fix: normalize os and arch in telemetry payload

Map 'Mac OS X' -> 'darwin', 'aarch64' -> 'arm64' for consistency
across SDKs.

* fix: update stale javadoc for sdkEndpoint parameter

* fix: replace hardcoded version fallback with "unknown"

Avoids manual drift risk when the version bumps but the fallback
string is forgotten. pom.properties and manifest should always
resolve in packaged JARs.

* fix: guard compareSemver against unknown version, normalize amd64, use try-with-resources

- Skip version compatibility warning when SDK_VERSION is "unknown"
  (prevents spurious warnings when running from source/IDE)
- Add amd64 -> x64 mapping in normalizeArch for Linux consistency
- Use try-with-resources for InputStream in detectSdkVersion

* feat: add auditToolCall method (#1260)

* fix: suppress telemetry for localhost endpoints

When the SDK endpoint is localhost, 127.0.0.1, or [::1], telemetry
pings are now suppressed unless telemetryEnabled is explicitly set
to true. Prevents telemetry leaks during local development.

Updated 4 tests to pass telemetryEnabled=true for WireMock
localhost endpoints.

* chore: bump version to 4.1.0

* fix: remove duplicate endpoint call in AuditToolCallTest

* docs: add v4.1.0 changelog entry

* docs: add v4.1.0 changelog entry

* docs: set v4.1.0 release date

Author: saurabhjain1592

CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [4.1.0] - 2026-03-14
+
+### Added
+
+- `auditToolCall()` — record non-LLM tool calls (API, MCP, function) in the audit trail. Returns audit ID, status, and timestamp. Requires Platform v5.1.0+
+- `getAuditLogsByTenant()` — retrieve audit logs for a tenant with optional pagination
+- `searchAuditLogs()` — search audit logs with filters (client ID, request type, limit)
+
+### Fixed
+
+- Telemetry pings now suppressed for localhost/127.0.0.1/[::1] endpoints unless `telemetryEnabled` is explicitly set to `true`. Prevents telemetry noise during local development.
+
+---
+
 ## [4.0.0] - 2026-03-09
 
 ### Breaking Changes

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.getaxonflow</groupId>
     <artifactId>axonflow-sdk</artifactId>
-    <version>4.0.0</version>
+    <version>4.1.0</version>
     <packaging>jar</packaging>
 
     <name>AxonFlow Java SDK</name>

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -261,6 +261,7 @@ public HealthStatus healthCheck() {
 
         if (status.getSdkCompatibility() != null
                 && status.getSdkCompatibility().getMinSdkVersion() != null
+                && !"unknown".equals(AxonFlowConfig.SDK_VERSION)
                 && compareSemver(AxonFlowConfig.SDK_VERSION, status.getSdkCompatibility().getMinSdkVersion()) < 0) {
             logger.warn("SDK version {} is below minimum supported version {}. Please upgrade.",
                     AxonFlowConfig.SDK_VERSION, status.getSdkCompatibility().getMinSdkVersion());
@@ -597,6 +598,57 @@ public CompletableFuture<AuditSearchResponse> getAuditLogsByTenantAsync(String t
         return CompletableFuture.supplyAsync(() -> getAuditLogsByTenant(tenantId, options), asyncExecutor);
     }
 
+    // ========================================================================
+    // Audit Tool Call
+    // ========================================================================
+
+    /**
+     * Audits a non-LLM tool call for compliance and observability.
+     *
+     * <p>Records tool invocations such as function calls, MCP operations,
+     * or API calls to the audit log.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * AuditToolCallResponse response = axonflow.auditToolCall(
+     *     AuditToolCallRequest.builder()
+     *         .toolName("web_search")
+     *         .toolType("function")
+     *         .input(Map.of("query", "latest news"))
+     *         .output(Map.of("results", 5))
+     *         .workflowId("wf_123")
+     *         .durationMs(450L)
+     *         .success(true)
+     *         .build());
+     * }</pre>
+     *
+     * @param request the audit tool call request
+     * @return the audit tool call response with audit ID
+     * @throws NullPointerException if request is null
+     * @throws IllegalArgumentException if tool_name is null or empty
+     * @throws AxonFlowException if the audit fails
+     */
+    public AuditToolCallResponse auditToolCall(AuditToolCallRequest request) {
+        Objects.requireNonNull(request, "request cannot be null");
+
+        return retryExecutor.execute(() -> {
+            Request httpRequest = buildOrchestratorRequest("POST", "/api/v1/audit/tool-call", request);
+            try (Response response = httpClient.newCall(httpRequest).execute()) {
+                return parseResponse(response, AuditToolCallResponse.class);
+            }
+        }, "auditToolCall");
+    }
+
+    /**
+     * Asynchronously audits a non-LLM tool call.
+     *
+     * @param request the audit tool call request
+     * @return a future containing the audit tool call response
+     */
+    public CompletableFuture<AuditToolCallResponse> auditToolCallAsync(AuditToolCallRequest request) {
+        return CompletableFuture.supplyAsync(() -> auditToolCall(request), asyncExecutor);
+    }
+
     // ========================================================================
     // Proxy Mode - Query Execution
     // ========================================================================

src/main/java/com/getaxonflow/sdk/AxonFlowConfig.java

@@ -20,8 +20,10 @@
 import com.getaxonflow.sdk.util.RetryConfig;
 import com.getaxonflow.sdk.util.CacheConfig;
 
+import java.io.InputStream;
 import java.time.Duration;
 import java.util.Objects;
+import java.util.Properties;
 
 /**
  * Configuration for the AxonFlow client.
@@ -42,8 +44,32 @@
  */
 public final class AxonFlowConfig {
 
-    /** SDK version string. */
-    public static final String SDK_VERSION = "3.8.0";
+    /** SDK version string, read from Maven pom.properties at runtime. */
+    public static final String SDK_VERSION = detectSdkVersion();
+
+    private static String detectSdkVersion() {
+        // Try Maven-generated pom.properties (available in packaged JAR)
+        try (InputStream is = AxonFlowConfig.class.getResourceAsStream(
+                    "/META-INF/maven/com.getaxonflow/axonflow-sdk/pom.properties")) {
+            if (is != null) {
+                Properties props = new Properties();
+                props.load(is);
+                String version = props.getProperty("version");
+                if (version != null && !version.isEmpty()) {
+                    return version;
+                }
+            }
+        } catch (Exception ignored) {
+            // Fall through to manifest check
+        }
+        // Try JAR manifest Implementation-Version
+        Package pkg = AxonFlowConfig.class.getPackage();
+        if (pkg != null && pkg.getImplementationVersion() != null) {
+            return pkg.getImplementationVersion();
+        }
+        // Fallback — "unknown" avoids hardcoded version drift
+        return "unknown";
+    }
 
     /** Default timeout for HTTP requests. */
     public static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(60);

src/main/java/com/getaxonflow/sdk/telemetry/TelemetryReporter.java

@@ -16,6 +16,7 @@
 package com.getaxonflow.sdk.telemetry;
 
 import com.getaxonflow.sdk.AxonFlowConfig;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
@@ -59,7 +60,7 @@ public class TelemetryReporter {
      * Sends an anonymous telemetry ping asynchronously (fire-and-forget).
      *
      * @param mode             the deployment mode (e.g. "production", "sandbox")
-     * @param sdkEndpoint      the configured SDK endpoint (unused in payload, present for future use)
+     * @param sdkEndpoint      the configured SDK endpoint, used to detect platform version via /health
      * @param telemetryEnabled config override for telemetry (null = use default based on mode)
      * @param debug            whether debug logging is enabled
      */
@@ -84,15 +85,25 @@ static void sendPing(String mode, String sdkEndpoint, Boolean telemetryEnabled,
             return;
         }
 
+        // Suppress telemetry for localhost endpoints unless explicitly enabled.
+        if (!Boolean.TRUE.equals(telemetryEnabled) && isLocalhostEndpoint(sdkEndpoint)) {
+            if (debug) {
+                logger.debug("Telemetry suppressed for localhost endpoint");
+            }
+            return;
+        }
+
         logger.info("AxonFlow: anonymous telemetry enabled. Opt out: AXONFLOW_TELEMETRY=off | https://docs.getaxonflow.com/telemetry");
 
         String endpoint = (checkpointUrl != null && !checkpointUrl.isEmpty())
                 ? checkpointUrl
                 : DEFAULT_ENDPOINT;
 
+        final String finalSdkEndpoint = sdkEndpoint;
         CompletableFuture.runAsync(() -> {
             try {
-                String payload = buildPayload(mode);
+                String platformVersion = detectPlatformVersion(finalSdkEndpoint);
+                String payload = buildPayload(mode, platformVersion);
 
                 OkHttpClient client = new OkHttpClient.Builder()
                         .connectTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
@@ -162,15 +173,19 @@ static boolean isEnabled(String mode, Boolean configOverride, boolean hasCredent
     /**
      * Builds the JSON payload for the telemetry ping.
      */
-    static String buildPayload(String mode) {
+    static String buildPayload(String mode, String platformVersion) {
         try {
             ObjectMapper mapper = new ObjectMapper();
             ObjectNode root = mapper.createObjectNode();
             root.put("sdk", "java");
             root.put("sdk_version", AxonFlowConfig.SDK_VERSION);
-            root.putNull("platform_version");
-            root.put("os", System.getProperty("os.name"));
-            root.put("arch", System.getProperty("os.arch"));
+            if (platformVersion != null) {
+                root.put("platform_version", platformVersion);
+            } else {
+                root.putNull("platform_version");
+            }
+            root.put("os", normalizeOS(System.getProperty("os.name")));
+            root.put("arch", normalizeArch(System.getProperty("os.arch")));
             root.put("runtime_version", System.getProperty("java.version"));
             root.put("deployment_mode", mode);
 
@@ -186,6 +201,76 @@ static String buildPayload(String mode) {
         }
     }
 
+    /**
+     * Detect platform version by calling the agent's /health endpoint.
+     * Returns null on any failure.
+     */
+    static String detectPlatformVersion(String sdkEndpoint) {
+        if (sdkEndpoint == null || sdkEndpoint.isEmpty()) {
+            return null;
+        }
+        try {
+            OkHttpClient client = new OkHttpClient.Builder()
+                    .connectTimeout(2, TimeUnit.SECONDS)
+                    .readTimeout(2, TimeUnit.SECONDS)
+                    .build();
+
+            Request request = new Request.Builder()
+                    .url(sdkEndpoint + "/health")
+                    .get()
+                    .build();
+
+            try (Response response = client.newCall(request).execute()) {
+                if (response.isSuccessful() && response.body() != null) {
+                    ObjectMapper mapper = new ObjectMapper();
+                    JsonNode root = mapper.readTree(response.body().string());
+                    JsonNode versionNode = root.get("version");
+                    if (versionNode != null && !versionNode.isNull() && !versionNode.asText().isEmpty()) {
+                        return versionNode.asText();
+                    }
+                }
+            }
+        } catch (Exception ignored) {
+            // Silent failure
+        }
+        return null;
+    }
+
+    /**
+     * Normalize OS name to lowercase short form consistent across SDKs.
+     * e.g. "Mac OS X" -> "darwin", "Windows 10" -> "windows", "Linux" -> "linux"
+     */
+    static String normalizeOS(String osName) {
+        if (osName == null) return "unknown";
+        String lower = osName.toLowerCase();
+        if (lower.contains("mac") || lower.contains("darwin")) return "darwin";
+        if (lower.contains("win")) return "windows";
+        if (lower.contains("linux")) return "linux";
+        return lower;
+    }
+
+    /**
+     * Normalize arch name consistent across SDKs.
+     * e.g. "aarch64" -> "arm64", "x86_64" -> "x64"
+     */
+    static String normalizeArch(String arch) {
+        if (arch == null) return "unknown";
+        if ("aarch64".equals(arch)) return "arm64";
+        if ("x86_64".equals(arch) || "amd64".equals(arch)) return "x64";
+        return arch;
+    }
+
+    /**
+     * Check whether the endpoint is a localhost address.
+     */
+    static boolean isLocalhostEndpoint(String endpoint) {
+        if (endpoint == null || endpoint.isEmpty()) {
+            return false;
+        }
+        String lower = endpoint.toLowerCase();
+        return lower.contains("localhost") || lower.contains("127.0.0.1") || lower.contains("[::1]");
+    }
+
     private TelemetryReporter() {
         // Utility class
     }