temporal-spring-ai: per-model ActivityOptions registry (#2855)

* temporal-spring-ai: plan — activity summaries for debuggability

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

* temporal-spring-ai: amend plan — limit summaries to chat + MCP

Narrows the activity-summaries scope to cases where the plugin itself owns
activity-stub creation. Activity-backed tool calls, Nexus tool calls, and
@SideEffectTool calls are now explicitly out of scope; the first two would
require per-call option overrides on user-owned stubs (no clean API), and
the third writes MarkerRecorded events which have no Summary field.

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

* temporal-spring-ai: add ActivitySummaryTest (chat path)

Runs a workflow that drives a single chat call through ActivityChatModel,
fetches the resulting history, and asserts the ActivityTaskScheduled event
for callChatModel carries a userMetadata Summary that starts with
"chat: default" and includes the user prompt. Intentionally fails against
unmodified chat code — the implementation follows in a subsequent commit.

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

* temporal-spring-ai: attach activity summaries for chat and MCP calls

ActivityChatModel.forModel() now stores the ActivityOptions it built and,
on each chat call, rebuilds the stub with a per-call Summary of the form
"chat: <model> · <first 60 chars of user prompt>". When a caller passes a
pre-built stub directly via the public constructors, behavior is unchanged
(no options known → no summary overlay).

ActivityMcpClient.create() does the same and adds a callTool(clientName,
request, summary) overload. McpToolCallback passes "mcp: <client>.<tool>".

Also fixes the activity-type-name casing in ActivitySummaryTest — Temporal
capitalizes the first character of method-name-derived activity types, so
the event carries "CallChatModel", not "callChatModel".

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

* temporal-spring-ai: drop PLAN.md

Planning scratchpad — not part of the shipped artifact. Removed before merge.

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

* temporal-spring-ai: drop user prompt from chat activity Summary

The Summary now carries only the model label ("chat: <model>") instead
of "chat: <model> · <first 60 chars of user prompt>". Including even a
truncated prompt leaks whatever the prompt contains — PII, secrets,
internal identifiers — into workflow history, server logs, and the
Temporal UI, which is a surprising default for an observability label.

An opt-in API for callers who explicitly want the prompt in the
Summary can be added later if there's demand.

ActivitySummaryTest.chatActivity_carriesModelOnlySummary_neverLeaksUserPrompt
asserts the Summary equals "chat: default" exactly and defensively
checks that no part of the prompt leaked in.

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

* 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>

* temporal-spring-ai: use @nullable annotations instead of Optional<>

Reverses the previous Optional<> commit in favor of @nullable on the
nullable fields/params. Matches the dominant convention in
temporal-sdk (431+ @nullable usages on public API surface) and avoids
a thicker runtime story for what is fundamentally a documentation /
IDE-hint concern (no NullAway in the build either way).

- ActivityChatModel: modelName and baseOptions fields + private ctor
  params are now @nullable String / @nullable ActivityOptions. Public
  ctors/factories accept nullable String modelName at the API
  boundary directly. getModelName() returns @nullable String.
- ActivityMcpClient: baseOptions field and callTool(..., summary)
  param use @nullable instead of Optional<>. 2-arg callTool passes
  null; McpToolCallback passes a plain String.
- ChatModelTypes.ChatModelActivityInput record: @nullable on
  modelName and modelOptions fields so deserialized readers see the
  nullability in the signature (per the reviewer's concern about the
  deserialization-side typesafety).

Consistent with org.springframework.lang.Nullable already used
elsewhere in this module (TemporalChatClient, SpringAiPlugin).

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

* temporal-spring-ai: use javax.annotation.Nullable for consistency

Switch the five files in this module that imported
org.springframework.lang.Nullable over to javax.annotation.Nullable
to match the dominant convention in sdk-java (197 usages vs. 7).

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

* temporal-spring-ai: plan — ActivityOptions overloads and non-retryable error classification

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

* temporal-spring-ai: amend plan — ActivityOptions overloads fix summaries UX wart

The activity-summaries branch only overlays Summaries when the factories
(forModel/create) built the stub. Users who need custom timeouts today fall
back to the public constructor, which silently drops UI Summaries. The
ActivityOptions overloads planned here are the proper fix: they let users
customize the stub and keep Summary labels. Plan now also covers deprecating
the public constructors with javadoc pointing at the factories.

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

* 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>

* temporal-spring-ai: drop PLAN.md

Planning scratchpad — not part of the shipped artifact. Removed before merge.

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

* temporal-spring-ai: remove (Duration, int) factory overloads

Now that forDefault(ActivityOptions) / forModel(String, ActivityOptions)
/ create(ActivityOptions) exist, the (Duration, int) convenience
overloads are asymmetric dead weight — they expose two of N ActivityOptions
fields as positional parameters, and callers wanting anything else
(heartbeats, task queue, custom retry backoff, ...) have to drop to the
ActivityOptions path anyway. Removed pre-release so the API surface is
consistent: no-arg → plugin defaults; ActivityOptions arg → caller options.

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

* temporal-spring-ai: plan — per-model ActivityOptions registry

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

* temporal-spring-ai: per-model ActivityOptions registry

SpringAiPlugin now accepts an optional Map<String, ActivityOptions>
keyed by chat-model bean name. On construction the plugin publishes
the map to a new package-public static registry SpringAiPluginOptions,
which ActivityChatModel.forModel(name) and forDefault() consult when
building the activity stub. Entries resolve by bean name; the reserved
key SpringAiPlugin.DEFAULT_MODEL_NAME ("default") covers forDefault().

Callers who pass explicit ActivityOptions via forModel(name, options)
or forDefault(options) bypass the registry entirely — explicit options
always win. The registry has no effect on the (timeout, maxAttempts)
convenience factory either; that still builds options from its args.

Auto-configuration picks up a user bean named
"chatModelActivityOptions" (constant
SpringAiTemporalAutoConfiguration.CHAT_MODEL_ACTIVITY_OPTIONS_BEAN) of
type Map<String, ActivityOptions>. The explicit bean-name qualifier
avoids Spring's collection-of-beans auto-wiring for Map<String, T>.

Tests: PerModelActivityOptionsTest covers the three cases called out
in the plan — registry hit, registry miss (falls back to default
2-minute timeout), and explicit options bypass.

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

* temporal-spring-ai: drop PLAN.md

Planning scratchpad — not part of the shipped artifact. Removed before merge.

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

* temporal-spring-ai: make per-model options compositional via 'default' catch-all

Address reviewer feedback on #2855: the three-way implicit fallback
(specific entry → library defaults) was ambiguous to readers of
forDefault() / forModel(name) — nothing locally tells the caller which
rung they land on. But a strict either-or (global OR exhaustive
per-model) breaks compositionality when a third-party starter
contributes a ChatModel bean your config didn't enumerate.

Resolution: keep per-model overrides, and reserve
ChatModelTypes.DEFAULT_MODEL_NAME as a user-declared catch-all key in
perModelOptions. Lookup is now map[name] ?? map["default"] ??
library defaults. SpringAiPlugin validates that every perModelOptions
key either matches a registered ChatModel bean or equals the catch-all
name; typos fail at plugin construction, not silently at call time.

Updates javadoc on SpringAiPlugin, ActivityChatModel.forModel(String),
and ChatModelActivityOptions. Collapses the duplicate "Activity
options" README section into one with an example of the catch-all
pattern. Adds tests for the catch-all lookup, specific-wins-over-
catch-all, and typo-key rejection.

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

---------

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

Author: donald-pinckney

temporal-spring-ai/README.md

@@ -64,6 +64,22 @@ ActivityChatModel chatModel = ActivityChatModel.forDefault(
                 .build());
 ```
 
+For configuration-driven per-model overrides, declare a `ChatModelActivityOptions` bean and auto-configuration wires the map into the plugin. A key equal to `ChatModelTypes.DEFAULT_MODEL_NAME` (the literal `"default"`) acts as a global catch-all: any chat model that lacks a bean-name-specific entry — including models contributed by third-party starters that your application did not declare directly — picks up that entry.
+
+```java
+@Bean
+ChatModelActivityOptions chatModelActivityOptions() {
+    ActivityOptions fiveMinute = ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+            .setStartToCloseTimeout(Duration.ofMinutes(5))
+            .build();
+    return new ChatModelActivityOptions(Map.of(
+            ChatModelTypes.DEFAULT_MODEL_NAME, fiveMinute,                             // global baseline
+            "claude", ActivityOptions.newBuilder(fiveMinute).setTaskQueue("claude-heavy").build())); // override
+}
+```
+
+Keys that neither match a registered ChatModel bean name nor equal `"default"` cause plugin construction to fail, so a typo surfaces at startup.
+
 `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.
@@ -187,24 +203,6 @@ Raw `byte[]` media gets serialized into every chat activity's input *and* result
 
 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.

temporal-spring-ai/src/main/java/io/temporal/springai/autoconfigure/ChatModelActivityOptions.java

@@ -0,0 +1,52 @@
+package io.temporal.springai.autoconfigure;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.springai.model.ActivityChatModel;
+import io.temporal.springai.plugin.SpringAiPlugin;
+import java.util.Map;
+
+/**
+ * Spring-bean wrapper for the per-model {@link ActivityOptions} map consumed by {@link
+ * SpringAiPlugin}. Inject this type into your config by declaring a bean that returns an instance
+ * of it:
+ *
+ * <pre>{@code
+ * @Bean
+ * ChatModelActivityOptions chatModelActivityOptions() {
+ *     return new ChatModelActivityOptions(Map.of(
+ *         "reasoning", ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+ *             .setStartToCloseTimeout(Duration.ofMinutes(15))
+ *             .build()));
+ * }
+ * }</pre>
+ *
+ * <p>The wrapper exists so auto-configuration can inject your options by <em>type</em>, not by bean
+ * name. Spring's default behavior for {@code Map<String, T>} injection is to collect every bean of
+ * type {@code T} into a map keyed by bean name — which for a generic type like {@code Map<String,
+ * ActivityOptions>} would sweep in any unrelated {@link ActivityOptions} bean you have in the
+ * context. Having a dedicated wrapper type avoids that collision entirely.
+ *
+ * <p>Keys are chat-model bean names; values are the full {@link ActivityOptions} to use when {@link
+ * ActivityChatModel#forModel(String)} / {@link ActivityChatModel#forDefault()} build the stub for
+ * that model. Use {@link ActivityChatModel#defaultActivityOptions()} as the baseline so the
+ * plugin's non-retryable-error classification is preserved.
+ *
+ * <p>A key equal to {@link io.temporal.springai.model.ChatModelTypes#DEFAULT_MODEL_NAME} (the
+ * literal {@code "default"}) acts as a global catch-all: any chat model that lacks a
+ * bean-name-specific entry — including models contributed by third-party starters that your
+ * application did not declare directly — picks up the {@code "default"} entry. Keys that neither
+ * match a registered ChatModel bean nor equal {@code "default"} cause plugin construction to fail.
+ *
+ * @param byModelName per-model-bean-name {@link ActivityOptions} overrides; may be empty
+ */
+public record ChatModelActivityOptions(Map<String, ActivityOptions> byModelName) {
+
+  public ChatModelActivityOptions {
+    byModelName = byModelName == null ? Map.of() : Map.copyOf(byModelName);
+  }
+
+  /** Returns an empty registry. */
+  public static ChatModelActivityOptions empty() {
+    return new ChatModelActivityOptions(Map.of());
+  }
+}

temporal-spring-ai/src/main/java/io/temporal/springai/autoconfigure/SpringAiTemporalAutoConfiguration.java

@@ -1,5 +1,6 @@
 package io.temporal.springai.autoconfigure;
 
+import io.temporal.activity.ActivityOptions;
 import io.temporal.springai.plugin.SpringAiPlugin;
 import java.util.Map;
 import org.springframework.ai.chat.model.ChatModel;
@@ -28,9 +29,32 @@
     name = {"org.springframework.ai.chat.model.ChatModel", "io.temporal.worker.Worker"})
 public class SpringAiTemporalAutoConfiguration {
 
+  /**
+   * Builds the {@link SpringAiPlugin}. Picks up an optional {@link ChatModelActivityOptions} bean
+   * and forwards its map to the plugin as per-model {@link ActivityOptions} overrides. The wrapper
+   * type exists so this auto-config can inject user options <em>by type</em> — trying to inject
+   * {@code Map<String, ActivityOptions>} directly would trigger Spring's collection-of-beans
+   * autowiring and sweep in any unrelated {@link ActivityOptions} bean in the context.
+   *
+   * <p>Example user config:
+   *
+   * <pre>{@code
+   * @Bean
+   * ChatModelActivityOptions chatModelActivityOptions() {
+   *     return new ChatModelActivityOptions(Map.of(
+   *         "reasoning", ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+   *             .setStartToCloseTimeout(Duration.ofMinutes(15))
+   *             .build()));
+   * }
+   * }</pre>
+   */
   @Bean
   public SpringAiPlugin springAiPlugin(
-      @Autowired Map<String, ChatModel> chatModels, ObjectProvider<ChatModel> primaryChatModel) {
-    return new SpringAiPlugin(chatModels, primaryChatModel.getIfUnique());
+      @Autowired Map<String, ChatModel> chatModels,
+      ObjectProvider<ChatModel> primaryChatModel,
+      ObjectProvider<ChatModelActivityOptions> perModelOptions) {
+    ChatModelActivityOptions options =
+        perModelOptions.getIfAvailable(ChatModelActivityOptions::empty);
+    return new SpringAiPlugin(chatModels, primaryChatModel.getIfUnique(), options.byModelName());
   }
 }

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

@@ -3,6 +3,8 @@
 import io.temporal.activity.ActivityOptions;
 import io.temporal.common.RetryOptions;
 import io.temporal.springai.activity.ChatModelActivity;
+import io.temporal.springai.plugin.SpringAiPlugin;
+import io.temporal.springai.plugin.SpringAiPluginOptions;
 import io.temporal.workflow.Workflow;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -102,16 +104,29 @@ private ActivityChatModel(
   }
 
   /**
-   * 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).
+   * Creates an ActivityChatModel for the default chat model.
+   *
+   * <p>Options resolution order:
+   *
+   * <ol>
+   *   <li>An entry registered on {@link SpringAiPlugin} under {@link
+   *       ChatModelTypes#DEFAULT_MODEL_NAME} in the per-model {@code ActivityOptions} map, if any.
+   *   <li>The plugin's default {@link ActivityOptions} (2-minute start-to-close, 3 attempts,
+   *       clearly permanent AI errors marked non-retryable).
+   * </ol>
+   *
+   * <p>Callers who want to set explicit options should use {@link #forDefault(ActivityOptions)} —
+   * explicit options bypass the registry entirely.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
    * @return an ActivityChatModel for the default chat model
    */
   public static ActivityChatModel forDefault() {
-    return forDefault(defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
+    ActivityOptions options =
+        SpringAiPluginOptions.optionsFor(ChatModelTypes.DEFAULT_MODEL_NAME)
+            .orElseGet(ActivityChatModel::defaultActivityOptions);
+    return forDefault(options);
   }
 
   /**
@@ -130,8 +145,21 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
   }
 
   /**
-   * Creates an ActivityChatModel for a specific chat model by bean name with the plugin's default
-   * {@link ActivityOptions}.
+   * Creates an ActivityChatModel for a specific chat model by bean name.
+   *
+   * <p>Options resolution order:
+   *
+   * <ol>
+   *   <li>An entry registered on {@link SpringAiPlugin} under {@code modelName} in the per-model
+   *       {@code ActivityOptions} map, if any.
+   *   <li>An entry registered under {@link ChatModelTypes#DEFAULT_MODEL_NAME} in the per-model map,
+   *       which acts as a user-declared catch-all for models without a specific entry.
+   *   <li>The plugin's default {@link ActivityOptions} (2-minute start-to-close, 3 attempts,
+   *       clearly permanent AI errors marked non-retryable).
+   * </ol>
+   *
+   * <p>Callers who want to set explicit options should use {@link #forModel(String,
+   * ActivityOptions)} — explicit options bypass the registry entirely.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
@@ -140,7 +168,11 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
    * @throws IllegalArgumentException if no model with that name exists (at activity runtime)
    */
   public static ActivityChatModel forModel(String modelName) {
-    return forModel(modelName, defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
+    ActivityOptions options =
+        SpringAiPluginOptions.optionsFor(modelName)
+            .or(() -> SpringAiPluginOptions.optionsFor(ChatModelTypes.DEFAULT_MODEL_NAME))
+            .orElseGet(ActivityChatModel::defaultActivityOptions);
+    return forModel(modelName, options);
   }
 
   /**

temporal-spring-ai/src/main/java/io/temporal/springai/plugin/SpringAiPlugin.java

@@ -1,5 +1,6 @@
 package io.temporal.springai.plugin;
 
+import io.temporal.activity.ActivityOptions;
 import io.temporal.common.SimplePlugin;
 import io.temporal.springai.activity.ChatModelActivityImpl;
 import io.temporal.springai.model.ChatModelTypes;
@@ -53,9 +54,7 @@ public class SpringAiPlugin extends SimplePlugin {
    * @param chatModel the Spring AI chat model to wrap as an activity
    */
   public SpringAiPlugin(ChatModel chatModel) {
-    super("io.temporal.spring-ai");
-    this.chatModels = Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, chatModel);
-    this.defaultModelName = ChatModelTypes.DEFAULT_MODEL_NAME;
+    this(Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, chatModel), null, Map.of());
   }
 
   /**
@@ -65,6 +64,31 @@ public SpringAiPlugin(ChatModel chatModel) {
    * @param primaryChatModel the primary chat model (used to determine default), or null
    */
   public SpringAiPlugin(Map<String, ChatModel> chatModels, @Nullable ChatModel primaryChatModel) {
+    this(chatModels, primaryChatModel, Map.of());
+  }
+
+  /**
+   * Creates a new SpringAiPlugin with multiple ChatModels and per-model {@link ActivityOptions}.
+   *
+   * <p>Entries in {@code perModelOptions} are keyed by chat-model bean name and consulted by {@link
+   * io.temporal.springai.model.ActivityChatModel#forModel(String)} and {@link
+   * io.temporal.springai.model.ActivityChatModel#forDefault()}. An entry whose key equals {@link
+   * ChatModelTypes#DEFAULT_MODEL_NAME} acts as a global catch-all: models without a
+   * bean-name-specific entry pick it up, including models contributed by third-party starters that
+   * the application did not declare directly. Keys that neither match a bean nor equal the
+   * catch-all name cause plugin construction to fail, so a typo'd model name surfaces early.
+   * Callers who pass explicit {@code ActivityOptions} to a factory bypass this map entirely.
+   *
+   * @param chatModels map of bean names to ChatModel instances
+   * @param primaryChatModel the primary chat model (used to determine default), or null
+   * @param perModelOptions per-model-name ActivityOptions overrides; may be empty
+   * @throws IllegalArgumentException if a key in {@code perModelOptions} neither matches a
+   *     registered ChatModel bean name nor equals {@link ChatModelTypes#DEFAULT_MODEL_NAME}
+   */
+  public SpringAiPlugin(
+      Map<String, ChatModel> chatModels,
+      @Nullable ChatModel primaryChatModel,
+      Map<String, ActivityOptions> perModelOptions) {
     super("io.temporal.spring-ai");
 
     if (chatModels == null || chatModels.isEmpty()) {
@@ -85,13 +109,35 @@ public SpringAiPlugin(Map<String, ChatModel> chatModels, @Nullable ChatModel pri
       this.defaultModelName = chatModels.keySet().iterator().next();
     }
 
+    if (perModelOptions != null) {
+      for (String key : perModelOptions.keySet()) {
+        if (!ChatModelTypes.DEFAULT_MODEL_NAME.equals(key) && !this.chatModels.containsKey(key)) {
+          throw new IllegalArgumentException(
+              "perModelOptions key '"
+                  + key
+                  + "' does not match any ChatModel bean. Registered models: "
+                  + this.chatModels.keySet()
+                  + ". Use '"
+                  + ChatModelTypes.DEFAULT_MODEL_NAME
+                  + "' as a catch-all for models without a specific entry.");
+        }
+      }
+    }
+    SpringAiPluginOptions.register(perModelOptions);
+
     if (chatModels.size() > 1) {
       log.info(
           "Registered {} chat models: {} (default: {})",
           chatModels.size(),
           chatModels.keySet(),
           defaultModelName);
     }
+    if (perModelOptions != null && !perModelOptions.isEmpty()) {
+      log.info(
+          "Registered per-model ActivityOptions overrides for {} model(s): {}",
+          perModelOptions.size(),
+          perModelOptions.keySet());
+    }
   }
 
   @Override

temporal-spring-ai/src/main/java/io/temporal/springai/plugin/SpringAiPluginOptions.java

@@ -0,0 +1,54 @@
+package io.temporal.springai.plugin;
+
+import io.temporal.activity.ActivityOptions;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Process-scoped registry of per-chat-model {@link ActivityOptions}, populated by {@link
+ * SpringAiPlugin} at worker construction and consulted by {@link
+ * io.temporal.springai.model.ActivityChatModel#forModel(String)} when building the activity stub.
+ *
+ * <p>The registry is a static singleton because the plugin is a worker-side object but the lookup
+ * happens in workflow code that runs on the same JVM. Populating a shared static map before any
+ * workflow executes is the cleanest way to bridge that without teaching workflow code about plugin
+ * instances.
+ *
+ * <p>Limitations:
+ *
+ * <ul>
+ *   <li>Only one set of per-model options per JVM. Running multiple plugins in the same worker
+ *       process with different per-model options is not supported — the last registration wins.
+ *   <li>Callers who invoke {@link io.temporal.springai.model.ActivityChatModel#forModel(String,
+ *       ActivityOptions)} or {@link
+ *       io.temporal.springai.model.ActivityChatModel#forDefault(ActivityOptions)} bypass the
+ *       registry — explicit options always win.
+ * </ul>
+ */
+public final class SpringAiPluginOptions {
+
+  private static final AtomicReference<Map<String, ActivityOptions>> REGISTRY =
+      new AtomicReference<>(Map.of());
+
+  private SpringAiPluginOptions() {}
+
+  /**
+   * Installs the given per-model-name {@link ActivityOptions}, replacing any previous entries.
+   * Called by {@link SpringAiPlugin}. A null or empty map clears the registry.
+   */
+  public static void register(Map<String, ActivityOptions> options) {
+    REGISTRY.set(options == null || options.isEmpty() ? Map.of() : Map.copyOf(options));
+  }
+
+  /**
+   * Returns the options registered for the given model name, or empty if none. A null {@code
+   * modelName} always returns empty.
+   */
+  public static Optional<ActivityOptions> optionsFor(String modelName) {
+    if (modelName == null) {
+      return Optional.empty();
+    }
+    return Optional.ofNullable(REGISTRY.get().get(modelName));
+  }
+}