Add nexus handler callbacks for SANO

CHANGELOG.md

@@ -7,6 +7,85 @@ This file contains assembled releases only.
 
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- Worker now warns when an activity method is registered from the class
+  instead of from an instance (i.e. its first parameter is an unbound `self`).
+- `workflow.new_random()` accepts an optional `name` that is mixed into the seed, so differently
+  named generators, and `workflow.random()`, produce different sequences.
+- **Experimental**: Standalone Nexus operations can report their outcome to a Nexus
+  service with completion callbacks. Pass `completion_callbacks` to
+  `NexusClient.start_operation` or `NexusClient.execute_operation`. Create the
+  callbacks with `temporalio.nexus.create_completion_callback`. When the
+  operation finishes, the server calls an on-complete operation on a worker for the
+  task queue of the callback. The call carries the result or the failure, and a source
+  context that you supply. The new `temporalio.nexus.notifications` module has the
+  input and output types of on-complete operations.
+
+### Changed
+
+- Payload converters exposed by data converters and workflow/activity accessors
+  retain transfer type conversion, so direct use behaves consistently with SDK
+  serialization.
+
+### Deprecated
+
+### :boom: Breaking Changes
+
+- `temporalio.contrib.google_adk_agents`: ADK-generated ids and retry jitter now draw from a
+  workflow-private deterministic stream (a `workflow.new_random()` per run) instead of
+  `workflow.random()`. A workflow started under 1.34.0 that generated
+  ADK ids or jitter (for example one waiting on a HITL response) may not replay
+  deterministically across this upgrade; drain such workflows or use worker versioning.
+- The OpenAI Agents integration has moved to the independently versioned
+  [`temporalio-openai-agents`](https://pypi.org/project/temporalio-openai-agents/)
+  package. The existing `temporalio[openai-agents]` extra now installs that
+  package, and the old public `temporalio.contrib.openai_agents` imports
+  remain available at runtime and retain their static type information.
+  New code should depend on `temporalio-openai-agents` directly and import
+  `temporalio.openai_agents`.
+- **Experimental**: Nexus Workflow Updates now require `wait_for_stage` to be explicitly set to `ACCEPTED`.
+- `temporalio.contrib.opentelemetry`: removed `TemporalIdGenerator.seed_span_id()` and
+  `seed_trace_id()`.
+
+### Fixed
+
+- Experimental Workflow Streams background publishing now retries transient
+  signal delivery failures without delaying payload conversion errors.
+- Fixed Pydantic constraints being silently ignored inside or outside workflow
+  sandboxes by passing through `annotated_types` by default.
+
+- `GoogleAdkPlugin`'s deterministic providers now work in read-only contexts (query handlers,
+  update validators), returning the workflow's deterministic time and fresh entropy without
+  touching the workflow's random state.
+- `contrib.google_adk_agents`: agents with an `output_schema` no longer fail every workflow task
+  when calling the model. The schema type is now sent to the model activity as its JSON schema.
+  Custom Pydantic schema generation is preserved.
+  Integer-valued output enums are normalized to strings to match Google GenAI.
+
+- `temporalio.contrib.strands` activity and MCP tools now give the model the
+  Activity's failure message and expose its exception to after-tool hooks.
+- Reject unsupported `InterpreterPoolExecutor` activity executors when creating
+  a worker instead of failing during activity execution.
+
+- Encoding a datetime search attribute without a timezone now raises
+  `ValueError("Timezone must be present on all search attribute dates")` on
+  the typed path, matching the deprecated untyped encoder, instead of sending
+  a naive ISO string that the server rejects with `BadSearchAttributes`.
+
+- `temporalio.contrib.opentelemetry`: `TracingInterceptor` and `OpenTelemetryInterceptor` no longer
+  log `Failed to detach context` when a context is torn down on a different thread while
+  OpenTelemetry's threading instrumentation (enabled by strands, among others) is active; a
+  context is now detached exactly when its token is still valid in the current
+  `contextvars.Context`, which it stays when a workflow resumes on another pool thread.
+
+- Decode enums that mix in `str` or `int` (for example `class Color(str, Enum)`) to the enum
+  instead of a list of characters or an error, and decode `dict` keys typed as an `int` enum.
+
+### Security
+
 ## [1.34.0] - 2026-09-30
 
 ### Added

changelog/added/dancing-firefly.md

@@ -0,0 +1 @@
+Add experimental Nexus Handler Callbacks for standalone Nexus operations through `NexusClient.start_operation`. Use `temporalio.nexus.create_completion_callback` to send the result or failure and source context to a Nexus handler.

pyproject.toml

@@ -281,3 +281,7 @@ package = false
 exclude-newer = "2 weeks"
 # The SDK compatibility extras need the newly published standalone integrations.
 exclude-newer-package = { temporalio-deepagents = false, temporalio-google-adk = false, temporalio-google-genai = false, temporalio-langgraph = false, temporalio-langsmith = false, temporalio-strands-agents = false }
+
+[tool.uv.sources]
+# TODO: Remove once a nexus-rpc release records the service of each operation
+nexus-rpc = { git = "https://github.com/nexus-rpc/sdk-python", rev = "e1d70abbb9378a8398fd472bd466c5dfa9f1aca7" }

scripts/gen_payload_visitor.py

@@ -12,6 +12,7 @@
 sys.path.insert(0, str(base_dir))
 
 from temporalio.api.common.v1.message_pb2 import Payload, Payloads, SearchAttributes
+from temporalio.api.notificationservice.v1 import OnCompleteRequest, OnCompleteResponse
 from temporalio.bridge.proto.nexus import NexusTaskCompletion
 from temporalio.bridge.proto.workflow_activation.workflow_activation_pb2 import (
     WorkflowActivation,
@@ -440,11 +441,14 @@ def write_bridge_visitors() -> None:
     out_path = base_dir / "temporalio" / "bridge" / "_visitor.py"
 
     # Build root descriptors: WorkflowActivation, WorkflowActivationCompletion,
-    # NexusTaskCompletion, and the system Nexus operation roots.
+    # NexusTaskCompletion, the system Nexus operation roots, and the notification
+    # service messages delivered to Nexus handler callbacks.
     roots: list[Descriptor] = [
         WorkflowActivation.DESCRIPTOR,
         WorkflowActivationCompletion.DESCRIPTOR,
         NexusTaskCompletion.DESCRIPTOR,
+        OnCompleteRequest.DESCRIPTOR,
+        OnCompleteResponse.DESCRIPTOR,
     ] + discover_system_nexus_roots()
 
     code = VisitorGenerator().generate(roots)

temporalio/bridge/_visitor.py

@@ -624,6 +624,21 @@ async def _visit_coresdk_nexus_NexusTaskCompletion(
         elif o.HasField("failure"):
             await self._visit_temporal_api_failure_v1_Failure(fs, o.failure)
 
+    async def _visit_temporal_api_notificationservice_v1_OnCompleteRequest(
+        self, fs: VisitorFunctions, o: Any
+    ):
+        if o.HasField("source_context"):
+            await self._visit_temporal_api_common_v1_Payload(fs, o.source_context)
+        if o.HasField("success"):
+            await self._visit_temporal_api_common_v1_Payload(fs, o.success)
+        elif o.HasField("failure"):
+            await self._visit_temporal_api_failure_v1_Failure(fs, o.failure)
+
+    async def _visit_temporal_api_notificationservice_v1_OnCompleteResponse(
+        self, fs: VisitorFunctions, o: Any
+    ) -> None:
+        pass
+
     async def _visit_temporal_api_common_v1_Header(self, fs: VisitorFunctions, o: Any):
         for v in o.fields.values():
             await self._visit_temporal_api_common_v1_Payload(fs, v)

temporalio/client/_impl.py

@@ -1580,6 +1580,11 @@ async def start_nexus_operation(
                 "temporalio.api.enums.v1.NexusOperationIdConflictPolicy.ValueType",
                 int(input.id_conflict_policy),
             ),
+            # Callback source contexts use the started operation's serialization
+            # context, like the rest of the request.
+            completion_callbacks=[
+                await cb._to_proto(data_converter) for cb in input.completion_callbacks
+            ],
         )
 
         if input.schedule_to_close_timeout is not None:

temporalio/client/_interceptor.py

@@ -18,6 +18,7 @@
 import temporalio.api.common.v1
 import temporalio.api.workflowservice.v1
 import temporalio.common
+import temporalio.nexus
 from temporalio.converter import DataConverter
 
 if TYPE_CHECKING:
@@ -605,6 +606,7 @@ class StartNexusOperationInput:
     headers: Mapping[str, str]
     rpc_metadata: Mapping[str, str | bytes]
     rpc_timeout: timedelta | None
+    completion_callbacks: Sequence[temporalio.nexus.CompletionCallback[Any]] = ()
 
 
 @dataclass