temporal-spring-ai: accept ActivityOptions and classify non-retryable AI errors

- ActivityChatModel.forDefault(ActivityOptions) and forModel(String,
  ActivityOptions) overloads added. New public defaultActivityOptions()
  returns the plugin's default bundle so callers can tweak one field
  without losing the other sensible defaults.
- ActivityMcpClient.create(ActivityOptions) + defaultActivityOptions()
  added, mirroring the chat side.
- Default RetryOptions for chat calls now mark
  org.springframework.ai.retry.NonTransientAiException and
  java.lang.IllegalArgumentException non-retryable. Default options for
  MCP calls mark IllegalArgumentException non-retryable. User-supplied
  ActivityOptions pass through verbatim — the plugin does not augment
  them.
- new ActivityChatModel(...) and new ActivityMcpClient(activity)
  constructors are @deprecated with javadoc pointing at the factories —
  they still work at runtime but skip the UI Summary labels the
  plugin-owned stub path attaches, which is now called out explicitly.
- README: new "Activity options and retry behavior" section documents
  the defaults, how to customize, and the Summary/factory connection.
- Tests: two new suites — ActivityOptionsAndRetryTest covers the
  non-retryable classification (1 attempt for NonTransientAiException,
  3 attempts for transient RuntimeException, custom task queue landing
  on the scheduled activity); ActivitySummaryTest gains a regression
  test asserting forDefault(customOptions) still emits UI Summaries.
- build.gradle: spring-ai-retry added as a testImplementation so tests
  can reference NonTransientAiException directly.

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

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.
+
+> **UI labels:** the Temporal UI labels chat and MCP rows with a short Summary (`chat: <model> · <prompt>`, `mcp: <client>.<tool>`) — but only when the activity stub is built via one of the factories above. The legacy `new ActivityChatModel(stub)` / `new ActivityMcpClient(activity)` constructors are deprecated and do not produce UI labels.
+
 ## 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/mcp/ActivityMcpClient.java

@@ -5,6 +5,7 @@
 import io.temporal.common.RetryOptions;
 import io.temporal.workflow.Workflow;
 import java.time.Duration;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -47,6 +48,18 @@ 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;
@@ -55,8 +68,16 @@ public class ActivityMcpClient {
   /**
    * Creates a new ActivityMcpClient with the given activity stub.
    *
+   * <p><strong>Note:</strong> this constructor does not label scheduled MCP activities with a
+   * Summary in the Temporal UI, because the plugin doesn't know the {@link ActivityOptions} the
+   * caller used to build {@code activity}. Prefer {@link #create()} or {@link
+   * #create(ActivityOptions)} when you want UI labels.
+   *
    * @param activity the activity stub for MCP operations
+   * @deprecated Prefer {@link #create()} / {@link #create(ActivityOptions)} — those keep the UI
+   *     Summary labels the plugin attaches to each MCP tool call.
    */
+  @Deprecated
   public ActivityMcpClient(McpClientActivity activity) {
     this(activity, null);
   }
@@ -72,18 +93,20 @@ private ActivityMcpClient(McpClientActivity activity, ActivityOptions baseOption
   }
 
   /**
-   * 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 with a custom timeout and attempt count. Other defaults
+   * (non-retryable error classification) are preserved.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
@@ -92,15 +115,50 @@ public static ActivityMcpClient create() {
    * @return a new ActivityMcpClient
    */
   public static ActivityMcpClient create(Duration timeout, int maxAttempts) {
-    ActivityOptions options =
-        ActivityOptions.newBuilder()
-            .setStartToCloseTimeout(timeout)
-            .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(maxAttempts).build())
-            .build();
+    return create(defaultActivityOptions(timeout, maxAttempts));
+  }
+
+  /**
+   * 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 options the activity options to use for each MCP call
+   * @return a new ActivityMcpClient
+   */
+  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();
+  }
+
   /**
    * Gets the server capabilities for all connected MCP clients.
    *

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

@@ -83,6 +83,20 @@ public class ActivityChatModel implements ChatModel {
   /** Default maximum retry attempts for chat model activity calls. */
   public static final int DEFAULT_MAX_ATTEMPTS = 3;
 
+  /**
+   * Error types that the default retry policy treats as non-retryable. These represent clearly
+   * permanent failures — a bad API key, an invalid prompt, an unknown model name — where retrying
+   * wastes time and money.
+   *
+   * <p>Applied only to the factories that build {@link ActivityOptions} internally. When callers
+   * pass their own {@link ActivityOptions} (via {@link #forDefault(ActivityOptions)} or {@link
+   * #forModel(String, ActivityOptions)}), their {@link RetryOptions} are used verbatim.
+   */
+  public static final List<String> DEFAULT_NON_RETRYABLE_ERROR_TYPES =
+      List.of(
+          "org.springframework.ai.retry.NonTransientAiException",
+          "java.lang.IllegalArgumentException");
+
   private final ChatModelActivity chatModelActivity;
   private final String modelName;
   private final ActivityOptions baseOptions;
@@ -92,18 +106,33 @@ public class ActivityChatModel implements ChatModel {
   /**
    * Creates a new ActivityChatModel that uses the default chat model.
    *
+   * <p><strong>Note:</strong> this constructor does not label the scheduled chat activity with a
+   * Summary in the Temporal UI, because the plugin doesn't know the {@link ActivityOptions} the
+   * caller used to build {@code chatModelActivity}. Prefer {@link #forDefault()} or {@link
+   * #forDefault(ActivityOptions)} when you want the UI labels.
+   *
    * @param chatModelActivity the activity stub for calling the chat model
+   * @deprecated Prefer {@link #forDefault()} / {@link #forDefault(ActivityOptions)} — those keep
+   *     the UI Summary labels the plugin attaches to each chat call.
    */
+  @Deprecated
   public ActivityChatModel(ChatModelActivity chatModelActivity) {
     this(chatModelActivity, null, null);
   }
 
   /**
    * Creates a new ActivityChatModel that uses a specific chat model.
    *
+   * <p><strong>Note:</strong> this constructor does not label the scheduled chat activity with a
+   * Summary in the Temporal UI. Prefer {@link #forModel(String)} or {@link #forModel(String,
+   * ActivityOptions)} when you want the UI labels.
+   *
    * @param chatModelActivity the activity stub for calling the chat model
    * @param modelName the name of the chat model to use, or null for default
+   * @deprecated Prefer {@link #forModel(String)} / {@link #forModel(String, ActivityOptions)} —
+   *     those keep the UI Summary labels the plugin attaches to each chat call.
    */
+  @Deprecated
   public ActivityChatModel(ChatModelActivity chatModelActivity, String modelName) {
     this(chatModelActivity, modelName, null);
   }
@@ -123,24 +152,36 @@ private ActivityChatModel(
   }
 
   /**
-   * Creates an ActivityChatModel for the default chat model.
-   *
-   * <p>This factory method creates the activity stub internally with default timeout and retry
-   * options.
+   * Creates an ActivityChatModel for the default chat model with the plugin's default {@link
+   * ActivityOptions} (2-minute start-to-close timeout, 3 attempts, clearly permanent AI errors
+   * marked non-retryable).
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
    * @return an ActivityChatModel for the default chat model
    */
   public static ActivityChatModel forDefault() {
-    return forModel(null, DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS);
+    return forDefault(defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
   }
 
   /**
-   * Creates an ActivityChatModel for a specific chat model by bean name.
+   * Creates an ActivityChatModel for the default chat model using the supplied {@link
+   * ActivityOptions}. Pass this when you need a specific task queue, heartbeat, priority, or a
+   * custom {@link RetryOptions} — anything the {@code (timeout, maxAttempts)} convenience factory
+   * can't express.
+   *
+   * <p><strong>Must be called from workflow code.</strong>
    *
-   * <p>This factory method creates the activity stub internally with default timeout and retry
-   * options.
+   * @param options the activity options to use for each chat call
+   * @return an ActivityChatModel for the default chat model
+   */
+  public static ActivityChatModel forDefault(ActivityOptions options) {
+    return forModel(null, options);
+  }
+
+  /**
+   * Creates an ActivityChatModel for a specific chat model by bean name with the plugin's default
+   * {@link ActivityOptions}.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
@@ -149,11 +190,12 @@ public static ActivityChatModel forDefault() {
    * @throws IllegalArgumentException if no model with that name exists (at activity runtime)
    */
   public static ActivityChatModel forModel(String modelName) {
-    return forModel(modelName, DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS);
+    return forModel(modelName, defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
   }
 
   /**
-   * Creates an ActivityChatModel for a specific chat model with custom options.
+   * Creates an ActivityChatModel for a specific chat model with a custom timeout and attempt count.
+   * The remaining defaults (non-retryable error classification) are preserved.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
@@ -163,15 +205,53 @@ public static ActivityChatModel forModel(String modelName) {
    * @return an ActivityChatModel for the specified chat model
    */
   public static ActivityChatModel forModel(String modelName, Duration timeout, int maxAttempts) {
-    ActivityOptions options =
-        ActivityOptions.newBuilder()
-            .setStartToCloseTimeout(timeout)
-            .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(maxAttempts).build())
-            .build();
+    return forModel(modelName, defaultActivityOptions(timeout, maxAttempts));
+  }
+
+  /**
+   * Creates an ActivityChatModel for a specific chat model using the supplied {@link
+   * ActivityOptions}. The provided options are used verbatim — the plugin does not augment the
+   * caller's {@link RetryOptions} or merge in its defaults. If you want the plugin-default
+   * non-retryable error classification, copy {@link #DEFAULT_NON_RETRYABLE_ERROR_TYPES} into your
+   * own {@link RetryOptions}.
+   *
+   * <p><strong>Must be called from workflow code.</strong>
+   *
+   * @param modelName the bean name of the chat model, or null for default
+   * @param options the activity options to use for each chat call
+   * @return an ActivityChatModel for the specified chat model
+   */
+  public static ActivityChatModel forModel(String modelName, ActivityOptions options) {
     ChatModelActivity activity = Workflow.newActivityStub(ChatModelActivity.class, options);
     return new ActivityChatModel(activity, modelName, options);
   }
 
+  /**
+   * Returns the plugin's default {@link ActivityOptions} for chat model calls. Useful as a starting
+   * point when you want to customize one or two fields without losing the sensible defaults:
+   *
+   * <pre>{@code
+   * ActivityChatModel.forDefault(
+   *     ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+   *         .setTaskQueue("chat-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();
+  }
+
   /**
    * Returns the name of the chat model this instance uses.
    *