Merge branch 'master' into spring-ai/provider-options-passthrough

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:
@@ -97,6 +114,109 @@ public class MyTools {
 
 Auto-detected and executed as Nexus operations, similar to activity stubs.
 
+## Migrating from plain Spring AI
+
+The plugin is designed so that bringing an existing Spring AI service onto Temporal is a localized change. Outside Temporal, you probably have something like:
+
+```java
+@Service
+class AssistantService {
+    private final ChatClient chatClient;
+
+    AssistantService(ChatModel chatModel) {
+        this.chatClient = ChatClient.builder(chatModel)
+                .defaultSystem("You are a helpful assistant.")
+                .defaultTools(new WeatherTools(), new MyTools())
+                .build();
+    }
+
+    String respond(String goal) {
+        return chatClient.prompt().user(goal).call().content();
+    }
+}
+```
+
+Inside a Temporal Workflow it becomes:
+
+```java
+@WorkflowInterface
+interface AssistantWorkflow { @WorkflowMethod String respond(String goal); }
+
+class AssistantWorkflowImpl implements AssistantWorkflow {
+    private final ChatClient chatClient;
+
+    @WorkflowInit
+    AssistantWorkflowImpl(String goal) {
+        WeatherActivity weather = Workflow.newActivityStub(WeatherActivity.class, opts);
+        this.chatClient = TemporalChatClient.builder(ActivityChatModel.forDefault())
+                .defaultSystem("You are a helpful assistant.")
+                .defaultTools(weather, new MyTools())
+                .build();
+    }
+
+    @Override
+    public String respond(String goal) {
+        return chatClient.prompt().user(goal).call().content();
+    }
+}
+```
+
+Three substitutions:
+
+| Outside Temporal | Inside a Temporal workflow |
+|---|---|
+| `ChatModel chatModel` (injected) | `ActivityChatModel.forDefault()` |
+| `ChatClient.builder(chatModel)` | `TemporalChatClient.builder(activityChatModel)` |
+| `new WeatherTools()` for a plain POJO tool | `Workflow.newActivityStub(WeatherActivity.class, ...)` for a durable tool |
+
+Plain `@Tool` POJOs, `@SideEffectTool`-annotated classes, and Nexus service stubs all work the same way — see **Tool Types** above.
+
+## Media in messages
+
+If you attach media (images, audio, etc.) to a `UserMessage` or an `AssistantMessage`, prefer passing it by URI rather than raw bytes:
+
+```java
+// Good — only the URL crosses the activity boundary.
+Media image = new Media(MimeTypeUtils.IMAGE_PNG, URI.create("https://cdn.example.com/pic.png"));
+
+// Works, but size-limited — see below.
+Media image = new Media(MimeTypeUtils.IMAGE_PNG, new ByteArrayResource(bytes));
+```
+
+Raw `byte[]` media gets serialized into every chat activity's input *and* result payload, which end up inside Temporal workflow history events. Server-side history events have a fixed 2 MiB size limit; to leave headroom for messages, tool definitions, and options, the plugin enforces a **1 MiB default cap** on inline media bytes and fails fast with an `IllegalArgumentException` pointing you at the URI alternative.
+
+Override the cap by setting the system property `io.temporal.springai.maxMediaBytes` before your worker starts (pass a positive integer; `0` disables the check). For anything larger than a small thumbnail, the URI route is the right answer — have an activity write the bytes to blob storage, then pass only the URL into the conversation.
+
+## Activity options and retry behavior
+
+`ActivityChatModel.forDefault()` and `ActivityChatModel.forModel(name)` create 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` classified as non-retryable so a bad API key or invalid prompt fails fast.
+
+Override with `ActivityChatModel.forModel(name, ActivityOptions)`:
+
+```java
+ActivityOptions opts = ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+        .setStartToCloseTimeout(Duration.ofMinutes(10))
+        .setTaskQueue("reasoning-models")
+        .build();
+ActivityChatModel chatModel = ActivityChatModel.forModel("reasoning", opts);
+```
+
+For repeated per-model overrides, declare a `ChatModelActivityOptions` bean and auto-configuration wires the map into the plugin. See that class's javadoc for the pattern.
+
+`ActivityMcpClient.create()` / `create(ActivityOptions)` behave the same way with a 30-second default timeout.
+
+## Known limitations
+
+- **Streaming (`chatClient.stream(...)`)** — not currently supported. Use `.call()` instead.
+- **`defaultToolContext(Map<String, Object>)`** — not supported; tool context holds mutable state that can't safely cross the activity boundary. Pass required context as activity parameters or workflow state.
+- **Child workflow stubs as tools** — not supported. Wrap a plain `@Tool` method that starts the child workflow via `Workflow.newChildWorkflowStub(...)` and call through to it yourself.
+- **Media `byte[]` size** — inline bytes are capped at 1 MiB per payload (see "Media in messages" above). Prefer URI-based media.
+- **Provider-specific `ChatOptions` via `ChatClient.defaultOptions(...)`** — works as long as your `ChatOptions` subclass overrides `copy()` to return its own type (every real provider class does this). A subclass inheriting the default `copy()` loses its identity before the plugin sees it — same behavior as outside Temporal.
+
+## Observability
+
+`TemporalChatClient.builder(chatModel, observationRegistry, customConvention)` accepts a Micrometer `ObservationRegistry` for Spring AI-side chat client metrics. Temporal-side metrics (activity durations, retries) are emitted by the SDK's `MetricsScope` — see the [Temporal Java SDK observability docs](https://docs.temporal.io/develop/java/observability) for how to wire an OpenTelemetry or Prometheus exporter onto your workers. The two layers compose: Spring AI observations cover what the caller does; Temporal metrics cover what the scheduled activity does.
+
 ## Optional Integrations
 
 Auto-configured when their dependencies are on the classpath:

temporal-spring-ai/build.gradle

@@ -46,6 +46,11 @@ 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 McpPluginTest can mock/reference McpSyncClient directly.
+    testImplementation 'org.springframework.ai:spring-ai-mcp'
+    // 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/activity/ChatModelActivityImpl.java

@@ -62,8 +62,8 @@ private abstract static class ToolCallingChatOptionsMixin {}
    * @param chatModel the chat model to use
    */
   public ChatModelActivityImpl(ChatModel chatModel) {
-    this.chatModels = Map.of("default", chatModel);
-    this.defaultModelName = "default";
+    this.chatModels = Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, chatModel);
+    this.defaultModelName = ChatModelTypes.DEFAULT_MODEL_NAME;
   }
 
   /**
@@ -327,6 +327,7 @@ private ChatModelTypes.MediaContent fromMedia(Media media) {
     if (media.getData() instanceof String uri) {
       return new ChatModelTypes.MediaContent(mimeType, uri);
     } else if (media.getData() instanceof byte[] data) {
+      ChatModelTypes.checkMediaSize(data);
       return new ChatModelTypes.MediaContent(mimeType, data);
     }
     throw new IllegalArgumentException(

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.