Merge branch 'master' into spring-ai/response-metadata

Author: donald-pinckney

temporal-spring-ai/README.md

@@ -51,6 +51,23 @@ public String run(String goal) {
 }
 ```
 
+## Activity options and retry behavior
+
+`ActivityChatModel.forDefault()` / `forModel(name)` build the chat activity stub with sensible defaults: a 2-minute start-to-close timeout, 3 attempts, and `org.springframework.ai.retry.NonTransientAiException` + `java.lang.IllegalArgumentException` marked non-retryable so a bad API key or invalid prompt fails fast instead of churning through retries.
+
+When you need finer control — a specific task queue, heartbeats, priority, or a custom `RetryOptions` — pass an `ActivityOptions` directly:
+
+```java
+ActivityChatModel chatModel = ActivityChatModel.forDefault(
+        ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+                .setTaskQueue("chat-heavy")
+                .build());
+```
+
+`ActivityMcpClient.create()` / `create(ActivityOptions)` work the same way with a 30-second default timeout.
+
+The Temporal UI labels chat and MCP rows with a short Summary (`chat: <model>`, `mcp: <client>.<tool>`). `ActivityChatModel` and `ActivityMcpClient` are constructed only via these factories — there is no public constructor, so users can't accidentally end up in a code path that skips UI labels. Prompt text is deliberately not included in chat summaries to avoid leaking user input (which may contain PII, credentials, or other sensitive data) into workflow history and server logs.
+
 ## Tool Types
 
 Tools passed to `defaultTools()` are handled based on their type:

temporal-spring-ai/build.gradle

@@ -46,6 +46,9 @@ dependencies {
     testImplementation "org.mockito:mockito-core:${mockitoVersion}"
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testImplementation 'org.springframework.ai:spring-ai-rag'
+    // Needed only so tests can reference Spring AI's NonTransientAiException to
+    // verify the plugin's default retry classification.
+    testImplementation 'org.springframework.ai:spring-ai-retry'
 
     testRuntimeOnly group: 'ch.qos.logback', name: 'logback-classic', version: "${logbackVersion}"
     testRuntimeOnly "org.junit.platform:junit-platform-launcher"

temporal-spring-ai/src/main/java/io/temporal/springai/chat/TemporalChatClient.java

@@ -3,12 +3,12 @@
 import io.micrometer.observation.ObservationRegistry;
 import io.temporal.springai.util.TemporalToolUtil;
 import java.util.Map;
+import javax.annotation.Nullable;
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.client.DefaultChatClient;
 import org.springframework.ai.chat.client.DefaultChatClientBuilder;
 import org.springframework.ai.chat.client.observation.ChatClientObservationConvention;
 import org.springframework.ai.chat.model.ChatModel;
-import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -29,9 +29,7 @@
  * @WorkflowInit
  * public MyWorkflowImpl() {
  *     // Create the activity-backed chat model
- *     ChatModelActivity chatModelActivity = Workflow.newActivityStub(
- *             ChatModelActivity.class, activityOptions);
- *     ActivityChatModel activityChatModel = new ActivityChatModel(chatModelActivity);
+ *     ActivityChatModel activityChatModel = ActivityChatModel.forDefault();
  *
  *     // Create tools
  *     WeatherActivity weatherTool = Workflow.newActivityStub(WeatherActivity.class, opts);

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

@@ -5,7 +5,9 @@
 import io.temporal.common.RetryOptions;
 import io.temporal.workflow.Workflow;
 import java.time.Duration;
+import java.util.List;
 import java.util.Map;
+import javax.annotation.Nullable;
 
 /**
  * A workflow-safe wrapper for MCP (Model Context Protocol) client operations.
@@ -47,48 +49,80 @@ public class ActivityMcpClient {
   /** Default maximum retry attempts for MCP activity calls. */
   public static final int DEFAULT_MAX_ATTEMPTS = 3;
 
+  /**
+   * Error types that the default retry policy treats as non-retryable. {@link
+   * IllegalArgumentException} covers unknown-client-name lookups. Client-not-found is already
+   * thrown as an {@code ApplicationFailure} with {@code nonRetryable=true} and wins on its own.
+   *
+   * <p>Applied only to the factories that build {@link ActivityOptions} internally. When callers
+   * pass their own {@link ActivityOptions} via {@link #create(ActivityOptions)}, their {@link
+   * RetryOptions} are used verbatim.
+   */
+  public static final List<String> DEFAULT_NON_RETRYABLE_ERROR_TYPES =
+      List.of("java.lang.IllegalArgumentException");
+
   private final McpClientActivity activity;
+  private final ActivityOptions baseOptions;
   private Map<String, McpSchema.ServerCapabilities> serverCapabilities;
   private Map<String, McpSchema.Implementation> clientInfo;
 
-  /**
-   * Creates a new ActivityMcpClient with the given activity stub.
-   *
-   * @param activity the activity stub for MCP operations
-   */
-  public ActivityMcpClient(McpClientActivity activity) {
+  /** Use one of the {@link #create()} / {@link #create(ActivityOptions)} factories. */
+  private ActivityMcpClient(McpClientActivity activity, ActivityOptions baseOptions) {
     this.activity = activity;
+    this.baseOptions = baseOptions;
   }
 
   /**
-   * Creates an ActivityMcpClient with default options.
+   * Creates an ActivityMcpClient with the plugin's default {@link ActivityOptions} (30-second
+   * start-to-close timeout, 3 attempts, {@link IllegalArgumentException} marked non-retryable).
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
    * @return a new ActivityMcpClient
    */
   public static ActivityMcpClient create() {
-    return create(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS);
+    return create(defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
   }
 
   /**
-   * Creates an ActivityMcpClient with custom options.
+   * Creates an ActivityMcpClient using the supplied {@link ActivityOptions}. Pass this when you
+   * need a specific task queue, heartbeat, priority, or custom {@link RetryOptions}. The provided
+   * options are used verbatim — the plugin does not augment the caller's {@link RetryOptions}.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
-   * @param timeout the activity start-to-close timeout
-   * @param maxAttempts the maximum number of retry attempts
+   * @param options the activity options to use for each MCP call
    * @return a new ActivityMcpClient
    */
-  public static ActivityMcpClient create(Duration timeout, int maxAttempts) {
-    McpClientActivity activity =
-        Workflow.newActivityStub(
-            McpClientActivity.class,
-            ActivityOptions.newBuilder()
-                .setStartToCloseTimeout(timeout)
-                .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(maxAttempts).build())
-                .build());
-    return new ActivityMcpClient(activity);
+  public static ActivityMcpClient create(ActivityOptions options) {
+    McpClientActivity activity = Workflow.newActivityStub(McpClientActivity.class, options);
+    return new ActivityMcpClient(activity, options);
+  }
+
+  /**
+   * Returns the plugin's default {@link ActivityOptions} for MCP calls. Useful as a starting point
+   * when you want to tweak a field without losing the sensible defaults:
+   *
+   * <pre>{@code
+   * ActivityMcpClient.create(
+   *     ActivityOptions.newBuilder(ActivityMcpClient.defaultActivityOptions())
+   *         .setTaskQueue("mcp-heavy")
+   *         .build());
+   * }</pre>
+   */
+  public static ActivityOptions defaultActivityOptions() {
+    return defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS);
+  }
+
+  private static ActivityOptions defaultActivityOptions(Duration timeout, int maxAttempts) {
+    return ActivityOptions.newBuilder()
+        .setStartToCloseTimeout(timeout)
+        .setRetryOptions(
+            RetryOptions.newBuilder()
+                .setMaximumAttempts(maxAttempts)
+                .setDoNotRetry(DEFAULT_NON_RETRYABLE_ERROR_TYPES.toArray(new String[0]))
+                .build())
+        .build();
   }
 
   /**
@@ -127,7 +161,28 @@ public Map<String, McpSchema.Implementation> getClientInfo() {
    * @return the tool call result
    */
   public McpSchema.CallToolResult callTool(String clientName, McpSchema.CallToolRequest request) {
-    return activity.callTool(clientName, request);
+    return callTool(clientName, request, null);
+  }
+
+  /**
+   * Calls a tool on a specific MCP client, attaching the given activity Summary to the scheduled
+   * activity so it renders meaningfully in the Temporal UI.
+   *
+   * @param clientName the name of the MCP client
+   * @param request the tool call request
+   * @param summary the activity Summary, or null to omit
+   * @return the tool call result
+   */
+  public McpSchema.CallToolResult callTool(
+      String clientName, McpSchema.CallToolRequest request, @Nullable String summary) {
+    if (summary == null) {
+      return activity.callTool(clientName, request);
+    }
+    McpClientActivity stub =
+        Workflow.newActivityStub(
+            McpClientActivity.class,
+            ActivityOptions.newBuilder(baseOptions).setSummary(summary).build());
+    return stub.callTool(clientName, request);
   }
 
   /**

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

@@ -106,7 +106,8 @@ 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);
-    McpSchema.CallToolResult result = client.callTool(clientName, request);
+    String summary = "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.
     // For example, an "access denied" error lets the AI suggest a valid path.