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>

Author: donald-pinckney

temporal-spring-ai/PLAN.md

@@ -14,6 +14,32 @@ Two related production-readiness gaps:
    have to bypass the factories entirely and construct their own
    `Workflow.newActivityStub(ChatModelActivity.class, ...)`.
 
+### Interaction with the `spring-ai/activity-summaries` branch
+
+The summaries branch landed a plugin-owned `ActivityOptions` store on
+`ActivityChatModel` and `ActivityMcpClient`: the factories (`forModel`,
+`create`) now retain the options they built the stub with, and the per-call
+path overlays a Summary on top. The bare public constructors
+(`new ActivityChatModel(stub)`, `new ActivityMcpClient(activity)`) receive
+no options and therefore emit no summary — silently. That's a real UX wart:
+anyone who rolls their own stub today loses Summary labels on the chat /
+MCP rows in the Temporal UI.
+
+The `ActivityOptions` factory overloads this branch adds **are the proper
+fix** for that wart. Users who need non-default timeouts / retries / task
+queue / heartbeats today fall back to the public constructor to get those;
+giving them a factory that takes `ActivityOptions` means they keep
+summaries while still customizing the stub. This branch should therefore:
+
+- Explicitly document (in `ActivityChatModel` and `ActivityMcpClient`
+  javadocs, and the README) that Summary labels appear only when the stub
+  is built via one of the factories, and point at the new overloads as the
+  recommended path for customization.
+- Leave the public constructors in place for backward compatibility, but
+  mark them `@Deprecated` or, at minimum, add a javadoc note that they
+  skip UI summaries. Decision: ship the deprecation alongside the new
+  factory so the doc and the warning point to the same replacement.
+
 ## Files to change
 
 - `src/main/java/io/temporal/springai/model/ActivityChatModel.java`
@@ -23,11 +49,30 @@ Two related production-readiness gaps:
     an `ActivityOptions` internally that includes a default
     `RetryOptions.setDoNotRetry(...)` list (see §Retry classification below)
     and delegate to the new `ActivityOptions` overload.
-  - Keep all existing overloads working — purely additive API.
+  - The new overloads pass their `ActivityOptions` into the existing
+    private `(stub, modelName, baseOptions)` constructor added by the
+    summaries branch, so Summary labels work out of the box — no extra
+    wiring.
+  - Javadoc on the public `ActivityChatModel(ChatModelActivity[, String])`
+    constructors: add a note that callers who want UI Summaries should
+    prefer the new `forDefault(ActivityOptions)` / `forModel(String,
+    ActivityOptions)` factories. Mark the constructors `@Deprecated` with
+    a message pointing at the factory replacement.
+  - Keep all existing overloads working at runtime — purely additive API.
 
 - `src/main/java/io/temporal/springai/mcp/ActivityMcpClient.java`
   - Same treatment: add `create(ActivityOptions options)` overload; existing
     `create(timeout, maxAttempts)` delegates.
+  - Thread the passed `ActivityOptions` through the private
+    `(activity, baseOptions)` constructor added by the summaries branch so
+    `callTool(..., summary)` overlays work.
+  - `@Deprecated` the public `new ActivityMcpClient(activity)` constructor
+    with a javadoc note recommending the factory for Summary support.
+
+- `README.md`
+  - Brief note in the quick-start and the "Tool Types" section that chat
+    and MCP rows in the Temporal UI are labeled with Summaries when (and
+    only when) built via the factories.
 
 ### Retry classification
 
@@ -54,6 +99,11 @@ own, so no extra entries strictly required).
   `NonTransientAiException` does not trigger retry.
 - Unit test: default factory still retries on a transient `RuntimeException`
   (ensure the doNotRetry list doesn't over-reach).
+- Extend `ActivitySummaryTest` (added on the summaries branch) to assert a
+  workflow built via `ActivityChatModel.forDefault(customOptions)` still
+  carries the expected `chat: …` summary on its scheduled chat activity.
+  This guards against a regression where the new overloads silently drop
+  the `baseOptions` wiring.
 - `WorkflowReplayer` replay check.
 
 ## PR
@@ -70,15 +120,24 @@ own, so no extra entries strictly required).
 - Default RetryOptions for chat and MCP activities now include
   `doNotRetry` entries for clearly non-transient Spring AI failures
   (`NonTransientAiException`, `IllegalArgumentException`).
-- Existing factory signatures are preserved; they now delegate to the new
+- Public `new ActivityChatModel(...)` and `new ActivityMcpClient(...)`
+  constructors are `@Deprecated` with javadoc pointing at the factory
+  replacement. They still work at runtime but skip UI Summaries, which is
+  now called out explicitly.
+- Existing factory signatures are preserved; they delegate to the new
   `ActivityOptions` overloads.
 
 ## Why?
-Previously the only way to customize the chat or MCP activity stub was via
-`(timeout, maxAttempts)` — no heartbeats, task queue override, Summary,
+Previously the only way to customize the chat or MCP activity stub was
+via `(timeout, maxAttempts)` — no heartbeats, task queue override,
 priority, or `doNotRetry`. Users hitting those needs had to bypass the
-factories entirely. Also: transient-vs-permanent classification matters a
-lot for LLM calls (a 401 shouldn't retry for minutes), and the integration
-guide specifically calls out "tell Temporal which errors are retryable and
+factories and call the public constructor with a hand-built stub, which
+as of the summaries branch silently drops the Temporal UI labels for
+chat and MCP rows. The new `ActivityOptions` overloads close that gap:
+users get full customization *and* keep the Summary labels.
+
+Also: transient-vs-permanent classification matters a lot for LLM calls
+(a 401 shouldn't retry for minutes), and the integration guide
+specifically calls out "tell Temporal which errors are retryable and
 which are not." This brings the plugin in line.
 ```