temporal-spring-ai: wrap nullable fields/params in Optional<>

Addresses review feedback (thread on #2852) preferring typesafe
Optional<T> over nullable fields and raw null delegation. Three
sites changed:

- ActivityChatModel: modelName and baseOptions fields + private ctor
  params are now Optional<String> / Optional<ActivityOptions>.
  getModelName() returns Optional<String>. Public ctors and factories
  still accept nullable String modelName at the API boundary (matches
  prior javadoc: "null for default"); they normalize via
  Optional.ofNullable before storing. Internal readers use .map /
  .orElse instead of null checks.
- ActivityMcpClient: the 3-arg callTool's summary parameter is now
  Optional<String>. The 2-arg convenience overload passes
  Optional.empty(). The rebuild-with-summary branch uses
  .isPresent() + .get() instead of null checks.
- McpToolCallback.call(...) wraps its generated summary string in
  Optional.of(...) before passing to callTool.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: donald-pinckney

temporal-spring-ai/src/main/java/io/temporal/springai/mcp/ActivityMcpClient.java

@@ -6,6 +6,7 @@
 import io.temporal.workflow.Workflow;
 import java.time.Duration;
 import java.util.Map;
+import java.util.Optional;
 
 /**
  * A workflow-safe wrapper for MCP (Model Context Protocol) client operations.
@@ -48,7 +49,7 @@ public class ActivityMcpClient {
   public static final int DEFAULT_MAX_ATTEMPTS = 3;
 
   private final McpClientActivity activity;
-  private final ActivityOptions baseOptions;
+  private final Optional<ActivityOptions> baseOptions;
   private Map<String, McpSchema.ServerCapabilities> serverCapabilities;
   private Map<String, McpSchema.Implementation> clientInfo;
 
@@ -58,15 +59,16 @@ public class ActivityMcpClient {
    * @param activity the activity stub for MCP operations
    */
   public ActivityMcpClient(McpClientActivity activity) {
-    this(activity, null);
+    this(activity, Optional.empty());
   }
 
   /**
-   * Creates a new ActivityMcpClient. When {@code baseOptions} is non-null, {@link #callTool(String,
+   * Creates a new ActivityMcpClient. When {@code baseOptions} is present, {@link #callTool(String,
    * McpSchema.CallToolRequest, String)} rebuilds the activity stub with a per-call Summary on top
-   * of those options.
+   * of those options. When empty, the caller supplied a pre-built stub whose options we don't know,
+   * so we call through it as-is and drop any requested summary.
    */
-  private ActivityMcpClient(McpClientActivity activity, ActivityOptions baseOptions) {
+  private ActivityMcpClient(McpClientActivity activity, Optional<ActivityOptions> baseOptions) {
     this.activity = activity;
     this.baseOptions = baseOptions;
   }
@@ -98,7 +100,7 @@ public static ActivityMcpClient create(Duration timeout, int maxAttempts) {
             .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(maxAttempts).build())
             .build();
     McpClientActivity activity = Workflow.newActivityStub(McpClientActivity.class, options);
-    return new ActivityMcpClient(activity, options);
+    return new ActivityMcpClient(activity, Optional.of(options));
   }
 
   /**
@@ -137,7 +139,7 @@ public Map<String, McpSchema.Implementation> getClientInfo() {
    * @return the tool call result
    */
   public McpSchema.CallToolResult callTool(String clientName, McpSchema.CallToolRequest request) {
-    return callTool(clientName, request, null);
+    return callTool(clientName, request, Optional.empty());
   }
 
   /**
@@ -148,19 +150,22 @@ public McpSchema.CallToolResult callTool(String clientName, McpSchema.CallToolRe
    *
    * @param clientName the name of the MCP client
    * @param request the tool call request
-   * @param summary the activity Summary, or null to omit
+   * @param summary the activity Summary, or empty to omit
    * @return the tool call result
    */
   public McpSchema.CallToolResult callTool(
-      String clientName, McpSchema.CallToolRequest request, String summary) {
-    if (summary == null || baseOptions == null) {
-      return activity.callTool(clientName, request);
+      String clientName, McpSchema.CallToolRequest request, Optional<String> summary) {
+    // Overlay the summary onto a fresh stub only when both a summary is requested AND we have
+    // a recipe to rebuild the stub from (baseOptions). If either is missing, fall through to
+    // the cached activity — it already has baseOptions baked in if we knew them at construction.
+    if (summary.isPresent() && baseOptions.isPresent()) {
+      McpClientActivity stub =
+          Workflow.newActivityStub(
+              McpClientActivity.class,
+              ActivityOptions.newBuilder(baseOptions.get()).setSummary(summary.get()).build());
+      return stub.callTool(clientName, request);
     }
-    McpClientActivity stub =
-        Workflow.newActivityStub(
-            McpClientActivity.class,
-            ActivityOptions.newBuilder(baseOptions).setSummary(summary).build());
-    return stub.callTool(clientName, request);
+    return activity.callTool(clientName, request);
   }
 
   /**

temporal-spring-ai/src/main/java/io/temporal/springai/mcp/McpToolCallback.java

@@ -3,6 +3,7 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import org.springframework.ai.mcp.McpToolUtils;
 import org.springframework.ai.model.ModelOptionsUtils;
 import org.springframework.ai.tool.ToolCallback;
@@ -106,7 +107,7 @@ public String call(String toolInput) {
 
     // Use the original tool name (not prefixed) when calling the MCP server
     McpSchema.CallToolRequest request = new McpSchema.CallToolRequest(tool.name(), arguments);
-    String summary = "mcp: " + clientName + "." + tool.name();
+    Optional<String> summary = Optional.of("mcp: " + clientName + "." + tool.name());
     McpSchema.CallToolResult result = client.callTool(clientName, request, summary);
 
     // Return the result as-is (including errors) so the AI can handle them.

temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java

@@ -9,6 +9,7 @@
 import java.time.Duration;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Collectors;
 import org.springframework.ai.chat.messages.*;
 import org.springframework.ai.chat.metadata.ChatResponseMetadata;
@@ -84,8 +85,8 @@ public class ActivityChatModel implements ChatModel {
   public static final int DEFAULT_MAX_ATTEMPTS = 3;
 
   private final ChatModelActivity chatModelActivity;
-  private final String modelName;
-  private final ActivityOptions baseOptions;
+  private final Optional<String> modelName;
+  private final Optional<ActivityOptions> baseOptions;
   private final ToolCallingManager toolCallingManager;
   private final ToolExecutionEligibilityPredicate toolExecutionEligibilityPredicate;
 
@@ -95,7 +96,7 @@ public class ActivityChatModel implements ChatModel {
    * @param chatModelActivity the activity stub for calling the chat model
    */
   public ActivityChatModel(ChatModelActivity chatModelActivity) {
-    this(chatModelActivity, null, null);
+    this(chatModelActivity, Optional.empty(), Optional.empty());
   }
 
   /**
@@ -105,16 +106,20 @@ public ActivityChatModel(ChatModelActivity chatModelActivity) {
    * @param modelName the name of the chat model to use, or null for default
    */
   public ActivityChatModel(ChatModelActivity chatModelActivity, String modelName) {
-    this(chatModelActivity, modelName, null);
+    this(chatModelActivity, Optional.ofNullable(modelName), Optional.empty());
   }
 
   /**
    * Internal constructor used by {@link #forModel(String, Duration, int)} and friends. When {@code
-   * baseOptions} is non-null, each call rebuilds the activity stub with a per-call Summary on top
-   * of those options so the Temporal UI can label the chat activity meaningfully.
+   * baseOptions} is present, each call rebuilds the activity stub with a per-call Summary on top of
+   * those options so the Temporal UI can label the chat activity meaningfully. When empty, the
+   * caller supplied a pre-built stub whose options we don't know, so we call through it as-is
+   * without a summary.
    */
   private ActivityChatModel(
-      ChatModelActivity chatModelActivity, String modelName, ActivityOptions baseOptions) {
+      ChatModelActivity chatModelActivity,
+      Optional<String> modelName,
+      Optional<ActivityOptions> baseOptions) {
     this.chatModelActivity = chatModelActivity;
     this.modelName = modelName;
     this.baseOptions = baseOptions;
@@ -169,15 +174,14 @@ public static ActivityChatModel forModel(String modelName, Duration timeout, int
             .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(maxAttempts).build())
             .build();
     ChatModelActivity activity = Workflow.newActivityStub(ChatModelActivity.class, options);
-    return new ActivityChatModel(activity, modelName, options);
+    return new ActivityChatModel(activity, Optional.ofNullable(modelName), Optional.of(options));
   }
 
   /**
-   * Returns the name of the chat model this instance uses.
-   *
-   * @return the model name, or null if using the default model
+   * Returns the name of the chat model this instance uses, or empty if it uses the plugin default
+   * (the {@code @Primary} {@code ChatModel} bean or the first one registered).
    */
-  public String getModelName() {
+  public Optional<String> getModelName() {
     return modelName;
   }
 
@@ -232,12 +236,14 @@ private ChatResponse internalCall(Prompt prompt) {
   }
 
   private ChatModelActivity stubForCall(Prompt prompt) {
-    if (baseOptions == null) {
-      return chatModelActivity;
-    }
-    ActivityOptions withSummary =
-        ActivityOptions.newBuilder(baseOptions).setSummary(buildSummary()).build();
-    return Workflow.newActivityStub(ChatModelActivity.class, withSummary);
+    return baseOptions
+        .map(
+            base -> {
+              ActivityOptions withSummary =
+                  ActivityOptions.newBuilder(base).setSummary(buildSummary()).build();
+              return Workflow.newActivityStub(ChatModelActivity.class, withSummary);
+            })
+        .orElse(chatModelActivity);
   }
 
   /**
@@ -247,8 +253,7 @@ private ChatModelActivity stubForCall(Prompt prompt) {
    * observability label.
    */
   private String buildSummary() {
-    String label = modelName != null ? modelName : "default";
-    return "chat: " + label;
+    return "chat: " + modelName.orElse("default");
   }
 
   private ChatModelTypes.ChatModelActivityInput createActivityInput(Prompt prompt) {
@@ -290,7 +295,10 @@ private ChatModelTypes.ChatModelActivityInput createActivityInput(Prompt prompt)
       }
     }
 
-    return new ChatModelTypes.ChatModelActivityInput(modelName, messages, modelOptions, tools);
+    // The serialized record field is String (null = use activity-side default model), so unwrap
+    // at the serialization boundary. Within this class we keep modelName as Optional<String>.
+    return new ChatModelTypes.ChatModelActivityInput(
+        modelName.orElse(null), messages, modelOptions, tools);
   }
 
   private List<ChatModelTypes.Message> toActivityMessages(Message message) {