temporal-spring-ai: accept ActivityOptions and classify non-retryable AI errors by donald-pinckney · Pull Request #2853 · temporalio/sdk-java

donald-pinckney · 2026-04-21T21:09:27Z

Based on

temporal-spring-ai: attach activity summaries for chat and MCP calls #2852 — spring-ai/activity-summaries — adds the chat/MCP Summary plumbing this PR builds on

Merge that first; this PR will auto-retarget to master.

What was changed

ActivityChatModel.forDefault(ActivityOptions) and forModel(String, ActivityOptions) overloads added. New public defaultActivityOptions() returns the plugin's default bundle so callers can tweak one field (e.g., task queue) 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.
The public new ActivityChatModel(...) and new ActivityMcpClient(activity) constructors are removed. The factories are now the sole construction path. The module is pre-release so there are no pinned callers to migrate; the deprecate-then-remove cycle would be pure noise.
README: new "Activity options and retry behavior" section documents the defaults and how to customize via the ActivityOptions overload.
Tests: two new suites — ActivityOptionsAndRetryTest covers 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.

Why?

Two gaps the integration guide calls out:

Retry classification. Without a doNotRetry list, a bad API key or invalid-prompt error churned through retries + backoff before failing. The new defaults fail fast on clearly permanent failures while still retrying transient ones (network, 5xx, rate-limits).
Customization surface. The prior factory API only exposed (timeout, maxAttempts) — no heartbeats, task queue override, priority, or doNotRetry. Users hitting those needs had to call the public constructor with a hand-built stub. That path silently dropped the UI Summary labels the summaries branch (temporal-spring-ai: attach activity summaries for chat and MCP calls #2852) added, so users were forced to choose between customization and readability.

The new ActivityOptions overloads give users both. Removing the public constructors outright means users can't accidentally end up in a code path that skips UI labels — there's one way in, and it does the right thing.

Depends on #2852 (activity-summaries). The summary regression test in this PR only passes because that branch already landed the baseOptions plumbing the new overloads thread through.

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

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>

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>

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>

Planning scratchpad — not part of the shipped artifact. Removed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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>

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>

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>

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>

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

…ies 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>

@deprecated

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

Planning scratchpad — not part of the shipped artifact. Removed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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>

…-options # Conflicts: # temporal-spring-ai/src/main/java/io/temporal/springai/mcp/ActivityMcpClient.java # temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java # temporal-spring-ai/src/test/java/io/temporal/springai/ActivitySummaryTest.java

donald-pinckney and others added 4 commits April 21, 2026 15:52

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

5c378df

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

donald-pinckney force-pushed the spring-ai/retry-and-options branch from 2a76e4e to f967316 Compare April 21, 2026 21:19

This was referenced Apr 21, 2026

temporal-spring-ai: preserve Usage and RateLimit in ChatResponse metadata #2854

Merged

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

Open

donald-pinckney changed the base branch from master to spring-ai/activity-summaries April 21, 2026 22:04

temporal-spring-ai: drop PLAN.md

a33c9e0

Planning scratchpad — not part of the shipped artifact. Removed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

donald-pinckney force-pushed the spring-ai/retry-and-options branch from f967316 to 1310ba4 Compare April 22, 2026 16:07

donald-pinckney force-pushed the spring-ai/retry-and-options branch 3 times, most recently from f038d46 to 9528294 Compare April 22, 2026 19:10

donald-pinckney marked this pull request as ready for review April 22, 2026 19:50

donald-pinckney requested a review from a team as a code owner April 22, 2026 19:50

donald-pinckney and others added 8 commits April 22, 2026 19:32

temporal-spring-ai: plan — ActivityOptions overloads and non-retryabl…

2a824bb

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

temporal-spring-ai: drop PLAN.md

785a185

Planning scratchpad — not part of the shipped artifact. Removed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

donald-pinckney force-pushed the spring-ai/retry-and-options branch from 9528294 to 006d8ad Compare April 23, 2026 14:10

brianstrauch requested changes Apr 23, 2026

View reviewed changes

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

brianstrauch approved these changes Apr 23, 2026

View reviewed changes

mjameswh approved these changes Apr 23, 2026

View reviewed changes

Base automatically changed from spring-ai/activity-summaries to master April 23, 2026 19:13

donald-pinckney merged commit ccaf4a6 into master Apr 23, 2026
18 checks passed

donald-pinckney deleted the spring-ai/retry-and-options branch April 23, 2026 20:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

temporal-spring-ai: accept ActivityOptions and classify non-retryable AI errors#2853
donald-pinckney merged 15 commits intomasterfrom
spring-ai/retry-and-options

donald-pinckney commented Apr 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

donald-pinckney commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Based on

What was changed

Why?

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

donald-pinckney commented Apr 21, 2026 •

edited

Loading