feat: extract durable runtime support changes

Moves runtime, event, and session service changes to a separate branch.
These changes support deterministic execution required for durable integrations.

Author: marcusmotill

pr_description.md

@@ -0,0 +1,50 @@
+# Refactor: Temporal Integration Cleanup & Documentation
+
+## Summary
+This PR refactors the `TemporalPlugin` to remove implicit default configurations and adds comprehensive documentation for the ADK-Temporal integration. The goal is to make the integration stricter, clearer, and easier to debug by forcing explicit configuration from the user.
+
+## Key Changes
+
+### 1. `TemporalPlugin` Refactor
+*   **Removed Implicit Defaults**: The plugin no longer contains hardcoded default timeouts (previously 60s) or retry policies. Users must now explicitly provide `activity_options` when initializing the plugin.
+*   **Removed Magic Model Resolution**: Removed the fallback logic that attempted to guess the model name from the agent context if missing. Failed requests will now raise a clear `ValueError` instead of behaving unpredictably.
+*   **Simplified `before_model_callback`**: The interception hook is now a pure passthrough to `workflow.execute_activity` without additional logic or conditional checks (`workflow.in_workflow()` check removed to fail fast if misused).
+
+### 2. Documentation (`README.md`)
+*   Added a new `src/google/adk/integrations/temporal/README.md`.
+*   **Internals Explained**: Documented the "Interception Flow" (how it short-circuits ADK) and "Dynamic Activities" (how `AgentName.generate_content` works without registration).
+*   **Clear Usage Examples**: provided distinct, copy-pasteable snippets for **Agent Setup** (Workflow side) and **Worker Setup**, clarifying the role of `AdkWorkerPlugin`.
+
+## Impact
+*   **Safety**: Impossible to accidentally run with unsafe defaults.
+*   **Debuggability**: Errors are now explicit (missing options, missing model).
+*   **Clarity**: Users understand exactly *why* they are adding plugins (serialization, runtime determinism, activity routing) via the new docs.
+
+## Usage Example
+
+### Agent Side
+```python
+# You MUST now provide explicit options
+activity_options = {
+    "start_to_close_timeout": timedelta(minutes=1),
+    "retry_policy": RetryPolicy(maximum_attempts=3)
+}
+
+agent = Agent(
+    model="gemini-2.5-pro",
+    plugins=[
+        # Routes model calls to Temporal Activities
+        TemporalPlugin(activity_options=activity_options)
+    ]
+)
+```
+
+### Worker Side
+```python
+worker = Worker(
+    client,
+    task_queue="my-queue",
+    # Configures ADK Runtime, Pydantic Support & Unsandboxed Runner
+    plugins=[AdkWorkerPlugin()]
+)
+```

src/google/adk/events/event.py

@@ -18,6 +18,7 @@
 from typing import Optional
 import uuid
 
+from google.adk import runtime
 from google.genai import types
 from pydantic import alias_generators
 from pydantic import ConfigDict
@@ -70,7 +71,7 @@ class Event(LlmResponse):
   # Do not assign the ID. It will be assigned by the session.
   id: str = ''
   """The unique identifier of the event."""
-  timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())
+  timestamp: float = Field(default_factory=lambda: runtime.get_time())
   """The timestamp of the event."""
 
   def model_post_init(self, __context):
@@ -125,4 +126,4 @@ def has_trailing_code_execution_result(
 
   @staticmethod
   def new_id():
-    return str(uuid.uuid4())
+    return runtime.new_uuid()

src/google/adk/runtime.py

@@ -0,0 +1,53 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Runtime module for abstracting system primitives like time and UUIDs."""
+
+import time
+import uuid
+from typing import Callable
+
+_time_provider: Callable[[], float] = time.time
+_id_provider: Callable[[], str] = lambda: str(uuid.uuid4())
+
+
+def set_time_provider(provider: Callable[[], float]) -> None:
+  """Sets the provider for the current time.
+
+  Args:
+    provider: A callable that returns the current time in seconds since the
+      epoch.
+  """
+  global _time_provider
+  _time_provider = provider
+
+
+def set_id_provider(provider: Callable[[], str]) -> None:
+  """Sets the provider for generating unique IDs.
+
+  Args:
+    provider: A callable that returns a unique ID string.
+  """
+  global _id_provider
+  _id_provider = provider
+
+
+def get_time() -> float:
+  """Returns the current time in seconds since the epoch."""
+  return _time_provider()
+
+
+def new_uuid() -> str:
+  """Returns a new unique ID."""
+  return _id_provider()

src/google/adk/sessions/in_memory_session_service.py

@@ -22,6 +22,7 @@
 
 from typing_extensions import override
 
+from google.adk import runtime
 from . import _session_util
 from ..errors.already_exists_error import AlreadyExistsError
 from ..events.event import Event
@@ -108,14 +109,14 @@ def _create_session_impl(
     session_id = (
         session_id.strip()
         if session_id and session_id.strip()
-        else str(uuid.uuid4())
+        else runtime.new_uuid()
     )
     session = Session(
         app_name=app_name,
         user_id=user_id,
         id=session_id,
         state=session_state or {},
-        last_update_time=time.time(),
+        last_update_time=runtime.get_time(),
     )
 
     if app_name not in self.sessions:

tests/unittests/test_runtime.py

@@ -0,0 +1,56 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit tests for the runtime module."""
+
+import time
+import uuid
+import unittest
+from unittest.mock import MagicMock, patch
+
+from google.adk import runtime
+
+
+class TestRuntime(unittest.TestCase):
+
+    def tearDown(self):
+        # Reset providers to default after each test
+        runtime.set_time_provider(time.time)
+        runtime.set_id_provider(lambda: str(uuid.uuid4()))
+
+    def test_default_time_provider(self):
+        # Verify it returns a float that is close to now
+        now = time.time()
+        rt_time = runtime.get_time()
+        self.assertIsInstance(rt_time, float)
+        self.assertAlmostEqual(rt_time, now, delta=1.0)
+
+    def test_default_id_provider(self):
+        # Verify it returns a string uuid
+        uid = runtime.new_uuid()
+        self.assertIsInstance(uid, str)
+        # Should be parseable as uuid
+        uuid.UUID(uid)
+
+    def test_custom_time_provider(self):
+        # Test override
+        mock_time = 123456789.0
+        runtime.set_time_provider(lambda: mock_time)
+        self.assertEqual(runtime.get_time(), mock_time)
+
+    def test_custom_id_provider(self):
+        # Test override
+        mock_id = "test-id-123"
+        runtime.set_id_provider(lambda: mock_id)
+        self.assertEqual(runtime.new_uuid(), mock_id)