agentex-sdk 0.6.5__py3-none-any.whl → 0.7.0__py3-none-any.whl

agentex/_models.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import inspect
+import weakref
 from typing import TYPE_CHECKING, Any, Type, Union, Generic, TypeVar, Callable, Optional, cast
 from datetime import date, datetime
 from typing_extensions import (
@@ -256,15 +257,16 @@ class BaseModel(pydantic.BaseModel):
             mode: Literal["json", "python"] | str = "python",
             include: IncEx | None = None,
             exclude: IncEx | None = None,
+            context: Any | None = None,
             by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
+            exclude_computed_fields: bool = False,
             round_trip: bool = False,
             warnings: bool | Literal["none", "warn", "error"] = True,
-            context: dict[str, Any] | None = None,
-            serialize_as_any: bool = False,
             fallback: Callable[[Any], Any] | None = None,
+            serialize_as_any: bool = False,
         ) -> dict[str, Any]:
             """Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump
 
@@ -272,16 +274,24 @@ class BaseModel(pydantic.BaseModel):
 
             Args:
                 mode: The mode in which `to_python` should run.
-                    If mode is 'json', the dictionary will only contain JSON serializable types.
-                    If mode is 'python', the dictionary may contain any Python objects.
-                include: A list of fields to include in the output.
-                exclude: A list of fields to exclude from the output.
+                    If mode is 'json', the output will only contain JSON serializable types.
+                    If mode is 'python', the output may contain non-JSON-serializable Python objects.
+                include: A set of fields to include in the output.
+                exclude: A set of fields to exclude from the output.
+                context: Additional context to pass to the serializer.
                 by_alias: Whether to use the field's alias in the dictionary key if defined.
-                exclude_unset: Whether to exclude fields that are unset or None from the output.
-                exclude_defaults: Whether to exclude fields that are set to their default value from the output.
-                exclude_none: Whether to exclude fields that have a value of `None` from the output.
-                round_trip: Whether to enable serialization and deserialization round-trip support.
-                warnings: Whether to log warnings when invalid fields are encountered.
+                exclude_unset: Whether to exclude fields that have not been explicitly set.
+                exclude_defaults: Whether to exclude fields that are set to their default value.
+                exclude_none: Whether to exclude fields that have a value of `None`.
+                exclude_computed_fields: Whether to exclude computed fields.
+                    While this can be useful for round-tripping, it is usually recommended to use the dedicated
+                    `round_trip` parameter instead.
+                round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].
+                warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                    "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
+                fallback: A function to call when an unknown value is encountered. If not provided,
+                    a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
+                serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
             Returns:
                 A dictionary representation of the model.
@@ -298,6 +308,8 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
             if fallback is not None:
                 raise ValueError("fallback is only supported in Pydantic v2")
+            if exclude_computed_fields != False:
+                raise ValueError("exclude_computed_fields is only supported in Pydantic v2")
             dumped = super().dict(  # pyright: ignore[reportDeprecated]
                 include=include,
                 exclude=exclude,
@@ -314,15 +326,17 @@ class BaseModel(pydantic.BaseModel):
             self,
             *,
             indent: int | None = None,
+            ensure_ascii: bool = False,
             include: IncEx | None = None,
             exclude: IncEx | None = None,
+            context: Any | None = None,
             by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
+            exclude_computed_fields: bool = False,
             round_trip: bool = False,
             warnings: bool | Literal["none", "warn", "error"] = True,
-            context: dict[str, Any] | None = None,
             fallback: Callable[[Any], Any] | None = None,
             serialize_as_any: bool = False,
         ) -> str:
@@ -354,6 +368,10 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
             if fallback is not None:
                 raise ValueError("fallback is only supported in Pydantic v2")
+            if ensure_ascii != False:
+                raise ValueError("ensure_ascii is only supported in Pydantic v2")
+            if exclude_computed_fields != False:
+                raise ValueError("exclude_computed_fields is only supported in Pydantic v2")
             return super().json(  # type: ignore[reportDeprecated]
                 indent=indent,
                 include=include,
@@ -573,6 +591,9 @@ class CachedDiscriminatorType(Protocol):
     __discriminator__: DiscriminatorDetails
 
 
+DISCRIMINATOR_CACHE: weakref.WeakKeyDictionary[type, DiscriminatorDetails] = weakref.WeakKeyDictionary()
+
+
 class DiscriminatorDetails:
     field_name: str
     """The name of the discriminator field in the variant class, e.g.
@@ -615,8 +636,9 @@ class DiscriminatorDetails:
 
 
 def _build_discriminated_union_meta(*, union: type, meta_annotations: tuple[Any, ...]) -> DiscriminatorDetails | None:
-    if isinstance(union, CachedDiscriminatorType):
-        return union.__discriminator__
+    cached = DISCRIMINATOR_CACHE.get(union)
+    if cached is not None:
+        return cached
 
     discriminator_field_name: str | None = None
 
@@ -669,7 +691,7 @@ def _build_discriminated_union_meta(*, union: type, meta_annotations: tuple[Any,
         discriminator_field=discriminator_field_name,
         discriminator_alias=discriminator_alias,
     )
-    cast(CachedDiscriminatorType, union).__discriminator__ = details
+    DISCRIMINATOR_CACHE.setdefault(union, details)
     return details
 
 

agentex/_streaming.py

@@ -54,11 +54,12 @@ class Stream(Generic[_T]):
         process_data = self._client._process_response_data
         iterator = self._iter_events()
 
-        for sse in iterator:
-            yield process_data(data=sse.json(), cast_to=cast_to, response=response)
-
-        # As we might not fully consume the response stream, we need to close it explicitly
-        response.close()
+        try:
+            for sse in iterator:
+                yield process_data(data=sse.json(), cast_to=cast_to, response=response)
+        finally:
+            # Ensure the response is closed even if the consumer doesn't read all data
+            response.close()
 
     def __enter__(self) -> Self:
         return self
@@ -117,11 +118,12 @@ class AsyncStream(Generic[_T]):
         process_data = self._client._process_response_data
         iterator = self._iter_events()
 
-        async for sse in iterator:
-            yield process_data(data=sse.json(), cast_to=cast_to, response=response)
-
-        # As we might not fully consume the response stream, we need to close it explicitly
-        await response.aclose()
+        try:
+            async for sse in iterator:
+                yield process_data(data=sse.json(), cast_to=cast_to, response=response)
+        finally:
+            # Ensure the response is closed even if the consumer doesn't read all data
+            await response.aclose()
 
     async def __aenter__(self) -> Self:
         return self

agentex/_types.py

@@ -243,6 +243,9 @@ _T_co = TypeVar("_T_co", covariant=True)
 if TYPE_CHECKING:
     # This works because str.__contains__ does not accept object (either in typeshed or at runtime)
     # https://github.com/hauntsaninja/useful_types/blob/5e9710f3875107d068e7679fd7fec9cfab0eff3b/useful_types/__init__.py#L285
+    #
+    # Note: index() and count() methods are intentionally omitted to allow pyright to properly
+    # infer TypedDict types when dict literals are used in lists assigned to SequenceNotStr.
     class SequenceNotStr(Protocol[_T_co]):
         @overload
         def __getitem__(self, index: SupportsIndex, /) -> _T_co: ...
@@ -251,8 +254,6 @@ if TYPE_CHECKING:
         def __contains__(self, value: object, /) -> bool: ...
         def __len__(self) -> int: ...
         def __iter__(self) -> Iterator[_T_co]: ...
-        def index(self, value: Any, start: int = 0, stop: int = ..., /) -> int: ...
-        def count(self, value: Any, /) -> int: ...
         def __reversed__(self) -> Iterator[_T_co]: ...
 else:
     # just point this to a normal `Sequence` at runtime to avoid having to special case

agentex/_utils/_sync.py

@@ -1,10 +1,8 @@
 from __future__ import annotations
 
-import sys
 import asyncio
 import functools
-import contextvars
-from typing import Any, TypeVar, Callable, Awaitable
+from typing import TypeVar, Callable, Awaitable
 from typing_extensions import ParamSpec
 
 import anyio
@@ -15,34 +13,11 @@ T_Retval = TypeVar("T_Retval")
 T_ParamSpec = ParamSpec("T_ParamSpec")
 
 
-if sys.version_info >= (3, 9):
-    _asyncio_to_thread = asyncio.to_thread
-else:
-    # backport of https://docs.python.org/3/library/asyncio-task.html#asyncio.to_thread
-    # for Python 3.8 support
-    async def _asyncio_to_thread(
-        func: Callable[T_ParamSpec, T_Retval], /, *args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs
-    ) -> Any:
-        """Asynchronously run function *func* in a separate thread.
-
-        Any *args and **kwargs supplied for this function are directly passed
-        to *func*. Also, the current :class:`contextvars.Context` is propagated,
-        allowing context variables from the main thread to be accessed in the
-        separate thread.
-
-        Returns a coroutine that can be awaited to get the eventual result of *func*.
-        """
-        loop = asyncio.events.get_running_loop()
-        ctx = contextvars.copy_context()
-        func_call = functools.partial(ctx.run, func, *args, **kwargs)
-        return await loop.run_in_executor(None, func_call)
-
-
 async def to_thread(
     func: Callable[T_ParamSpec, T_Retval], /, *args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs
 ) -> T_Retval:
     if sniffio.current_async_library() == "asyncio":
-        return await _asyncio_to_thread(func, *args, **kwargs)
+        return await asyncio.to_thread(func, *args, **kwargs)
 
     return await anyio.to_thread.run_sync(
         functools.partial(func, *args, **kwargs),
@@ -53,10 +28,7 @@ async def to_thread(
 def asyncify(function: Callable[T_ParamSpec, T_Retval]) -> Callable[T_ParamSpec, Awaitable[T_Retval]]:
     """
     Take a blocking function and create an async one that receives the same
-    positional and keyword arguments. For python version 3.9 and above, it uses
-    asyncio.to_thread to run the function in a separate thread. For python version
-    3.8, it uses locally defined copy of the asyncio.to_thread function which was
-    introduced in python 3.9.
+    positional and keyword arguments.
 
     Usage:
 

agentex/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "agentex"
-__version__ = "0.6.5"  # x-release-please-version
+__version__ = "0.7.0"  # x-release-please-version

agentex/lib/cli/templates/default/manifest.yaml.j2

@@ -86,7 +86,7 @@ agent:
 
   # Optional: Set Environment variables for running your agent locally as well 
   # as for deployment later on
-  # env:
+  env: {}
   #   OPENAI_API_KEY: "<YOUR_OPENAI_API_KEY_HERE>"
   #   OPENAI_BASE_URL: "<YOUR_OPENAI_BASE_URL_HERE>"
   #   OPENAI_ORG_ID: "<YOUR_OPENAI_ORG_ID_HERE>"
@@ -100,13 +100,12 @@ deployment:
     repository: "" # Update with your container registry
     tag: "latest"  # Default tag, should be versioned in production
 
+  imagePullSecrets: [] # Update with your image pull secret names
+    # - name: my-registry-secret
+
   # Global deployment settings that apply to all clusters
-  # These can be overridden in cluster-specific files (deploy/*.yaml)
+  # These can be overridden in cluster-specific environments (environments.yaml)
   global:
-    agent:
-      name: "{{ agent_name }}"
-      description: "{{ description }}"
-    
     # Default replica count
     replicaCount: 1
     

agentex/lib/cli/templates/default/project/acp.py.j2

@@ -1,29 +1,56 @@
 from agentex.lib.sdk.fastacp.fastacp import FastACP
 from agentex.lib.types.fastacp import AsyncACPConfig
 from agentex.lib.types.acp import SendEventParams, CancelTaskParams, CreateTaskParams
+from agentex.lib.utils.logging import make_logger
+from agentex.types.text_content import TextContent
+from agentex.lib import adk
+
+
+logger = make_logger(__name__)
 
 
 # Create an ACP server
+# This sets up the core server that will handle task creation, events, and cancellation
+# The `type="base"` configuration is the default configuration for the ACP server
 acp = FastACP.create(
     acp_type="async",
-    config=AsyncACPConfig(type="base")
+    config=AsyncACPConfig(
+        type="base",
+    ),
 )
 
 
+# This handler is called first whenever a new task is created.
+# It's a good place to initialize any state or resources needed for the task.
 @acp.on_task_event_send
 async def handle_task_event_send(params: SendEventParams):
-    # For this tutorial, we print the parameters sent to the handler 
-    # so you can see where and how messages within a task are handled
-    print(f"Hello world! I just received this message: {params}")
+    # For this tutorial, we log the parameters sent to the handler 
+    # so you can see where and how messages within a long running task are handled
+    logger.info(f"Received task event send rpc: {params}")
+        
+    # 1. Echo back the client's message to show it in the UI. This is not done by default so the agent developer has full control over what is shown to the user.
+    await adk.messages.create(task_id=params.task.id, content=params.event.content)
+
+    # 2. Send a simple response message.
+    # In future tutorials, this is where we'll add more sophisticated response logic.
+    await adk.messages.create(
+        task_id=params.task.id,
+        content=TextContent(
+            author="agent",
+            content=f"Hello! I've received your message. I can't respond right now, but in future tutorials we'll see how you can get me to intelligently respond to your message.",
+        ),
+    )
 
 @acp.on_task_cancel
 async def handle_task_canceled(params: CancelTaskParams):
     # For this tutorial, we print the parameters sent to the handler 
     # so you can see where and how task cancellation is handled
-    print(f"Hello world! Task canceled: {params.task.id}") 
+    logger.info(f"Received task cancel rpc: {params}")
 
 @acp.on_task_create
 async def handle_task_create(params: CreateTaskParams):
-    # For this tutorial, we print the parameters sent to the handler 
+    # For this tutorial, we log the parameters sent to the handler 
     # so you can see where and how task creation is handled
-    print(f"Hello world! Task created: {params.task.id}")
+
+    # Here is where you can initialize any state or resources needed for the task.
+    logger.info(f"Received task create rpc: {params}")

agentex/lib/cli/templates/sync/manifest.yaml.j2

@@ -74,14 +74,14 @@ agent:
   # Optional: Credentials mapping
   # Maps Kubernetes secrets to environment variables
   # Common credentials include:
-  # credentials:
+  credentials: [] # Update with your credentials
   #   - env_var_name: OPENAI_API_KEY
   #     secret_name: openai-api-key
   #     secret_key: api-key
 
   # Optional: Set Environment variables for running your agent locally as well 
   # as for deployment later on
-  # env:
+  env: {} # Update with your environment variables
   #   OPENAI_API_KEY: "<YOUR_OPENAI_API_KEY_HERE>"
   #   OPENAI_BASE_URL: "<YOUR_OPENAI_BASE_URL_HERE>"
   #   OPENAI_ORG_ID: "<YOUR_OPENAI_ORG_ID_HERE>"
@@ -95,14 +95,13 @@ deployment:
   image:
     repository: "" # Update with your container registry
     tag: "latest"  # Default tag, should be versioned in production
+  
+  imagePullSecrets: [] # Update with your image pull secret names
+    # - name: my-registry-secret
 
   # Global deployment settings that apply to all clusters
-  # These can be overridden in cluster-specific files (deploy/*.yaml)
+  # These can be overridden in cluster-specific environments (environments.yaml)
   global:
-    agent:
-      name: "{{ agent_name }}"
-      description: "{{ description }}"
-    
     # Default replica count
     replicaCount: 1
     

agentex/lib/cli/templates/temporal/manifest.yaml.j2

@@ -106,7 +106,7 @@ agent:
   
   # Optional: Set Environment variables for running your agent locally as well 
   # as for deployment later on
-  # env:
+  env: {}
   #   OPENAI_API_KEY: "<YOUR_OPENAI_API_KEY_HERE>"
   #   OPENAI_BASE_URL: "<YOUR_OPENAI_BASE_URL_HERE>"
   #   OPENAI_ORG_ID: "<YOUR_OPENAI_ORG_ID_HERE>"
@@ -121,16 +121,12 @@ deployment:
     repository: "" # Update with your container registry
     tag: "latest"  # Default tag, should be versioned in production
 
-  imagePullSecrets:
-    - name: my-registry-secret  # Update with your image pull secret name
+  imagePullSecrets: [] # Update with your image pull secret name
+    # - name: my-registry-secret
 
   # Global deployment settings that apply to all clusters
-  # These can be overridden using --override-file with custom configuration files
+  # These can be overridden in cluster-specific environments (environments.yaml)
   global:
-    agent:
-      name: "{{ agent_name }}"
-      description: "{{ description }}"
-    
     # Default replica count
     replicaCount: 1
     

agentex/lib/core/temporal/plugins/claude_agents/__init__.py

@@ -0,0 +1,72 @@
+"""Claude Agents SDK integration with Temporal.
+
+This plugin provides integration between Claude Agents SDK and AgentEx's
+Temporal-based orchestration platform.
+
+Features:
+- Temporal activity wrapper for Claude SDK calls
+- Real-time streaming to Redis/UI
+- Session resume for conversation context
+- Tool call visibility (Read, Write, Bash, etc.)
+- Subagent support with nested tracing
+- Workspace isolation per task
+
+Architecture:
+- activities.py: Temporal activity definitions
+- message_handler.py: Message parsing and streaming logic
+- Reuses OpenAI's ContextInterceptor for context threading
+
+Usage:
+    from agentex.lib.core.temporal.plugins.claude_agents import (
+        run_claude_agent_activity,
+        create_workspace_directory,
+        ContextInterceptor,
+    )
+
+    # In worker
+    worker = AgentexWorker(
+        task_queue=queue_name,
+        interceptors=[ContextInterceptor()],
+    )
+
+    activities = get_all_activities()
+    activities.extend([run_claude_agent_activity, create_workspace_directory])
+
+    await worker.run(activities=activities, workflow=YourWorkflow)
+"""
+
+from agentex.lib.core.temporal.plugins.claude_agents.hooks import (
+    TemporalStreamingHooks,
+    create_streaming_hooks,
+)
+from agentex.lib.core.temporal.plugins.claude_agents.activities import (
+    run_claude_agent_activity,
+    create_workspace_directory,
+)
+from agentex.lib.core.temporal.plugins.claude_agents.message_handler import (
+    ClaudeMessageHandler,
+)
+
+# Reuse OpenAI's context threading - this is the key to streaming!
+from agentex.lib.core.temporal.plugins.openai_agents.interceptors.context_interceptor import (
+    ContextInterceptor,
+    streaming_task_id,
+    streaming_trace_id,
+    streaming_parent_span_id,
+)
+
+__all__ = [
+    # Activities
+    "run_claude_agent_activity",
+    "create_workspace_directory",
+    # Message handling
+    "ClaudeMessageHandler",
+    # Hooks
+    "create_streaming_hooks",
+    "TemporalStreamingHooks",
+    # Context threading (reused from OpenAI)
+    "ContextInterceptor",
+    "streaming_task_id",
+    "streaming_trace_id",
+    "streaming_parent_span_id",
+]

agentex/lib/core/temporal/plugins/claude_agents/activities.py

@@ -0,0 +1,154 @@
+"""Temporal activities for Claude Agents SDK integration."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from temporalio import activity
+from claude_agent_sdk import AgentDefinition, ClaudeSDKClient, ClaudeAgentOptions
+
+from agentex.lib.utils.logging import make_logger
+from agentex.lib.core.temporal.plugins.claude_agents.hooks import create_streaming_hooks
+from agentex.lib.core.temporal.plugins.claude_agents.message_handler import ClaudeMessageHandler
+from agentex.lib.core.temporal.plugins.openai_agents.interceptors.context_interceptor import (
+    streaming_task_id,
+    streaming_trace_id,
+    streaming_parent_span_id,
+)
+
+logger = make_logger(__name__)
+
+
+@activity.defn
+async def create_workspace_directory(task_id: str, workspace_root: str | None = None) -> str:
+    """Create workspace directory for task - runs as Temporal activity
+
+    Args:
+        task_id: Task ID for workspace directory name
+        workspace_root: Root directory for workspaces (defaults to .claude-workspace/ in cwd)
+
+    Returns:
+        Absolute path to created workspace
+    """
+    if workspace_root is None:
+        # Default to .claude-workspace in current directory
+        # Follows Claude SDK's .claude/ convention
+        workspace_root = os.path.join(os.getcwd(), ".claude-workspace")
+
+    workspace_path = os.path.join(workspace_root, task_id)
+    os.makedirs(workspace_path, exist_ok=True)
+    logger.info(f"Created workspace: {workspace_path}")
+    return workspace_path
+
+
+@activity.defn(name="run_claude_agent_activity")
+async def run_claude_agent_activity(
+    prompt: str,
+    workspace_path: str,
+    allowed_tools: list[str],
+    permission_mode: str = "acceptEdits",
+    system_prompt: str | None = None,
+    resume_session_id: str | None = None,
+    agents: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Execute Claude SDK - wrapped in Temporal activity
+
+    This activity:
+    1. Gets task_id from ContextVar (set by ContextInterceptor)
+    2. Configures Claude with workspace isolation and session resume
+    3. Runs Claude SDK and processes messages via ClaudeMessageHandler
+    4. Streams messages to UI in real-time
+    5. Returns session_id, usage, and cost for next turn
+
+    Args:
+        prompt: User message to send to Claude
+        workspace_path: Directory for file operations (cwd)
+        allowed_tools: List of tools Claude can use (include "Task" for subagents)
+        permission_mode: Permission mode (default: acceptEdits)
+        system_prompt: Optional system prompt override
+        resume_session_id: Optional session ID to resume conversation context
+        agents: Optional dict of subagent definitions for Task tool
+
+    Returns:
+        dict with "messages", "session_id", "usage", and "cost_usd" keys
+    """
+
+    # Get streaming context from ContextVars (set by interceptor)
+    task_id = streaming_task_id.get()
+    trace_id = streaming_trace_id.get()
+    parent_span_id = streaming_parent_span_id.get()
+
+    logger.info(
+        f"[run_claude_agent_activity] Starting - "
+        f"task_id={task_id}, workspace={workspace_path}, tools={allowed_tools}, "
+        f"resume={'YES' if resume_session_id else 'NO (new session)'}, "
+        f"subagents={list(agents.keys()) if agents else 'NONE'}"
+    )
+
+    # Reconstruct AgentDefinition objects from serialized dicts
+    # Temporal serializes dataclasses to dicts, need to recreate them
+    agent_defs = None
+    if agents:
+        agent_defs = {}
+        for name, agent_data in agents.items():
+            if isinstance(agent_data, AgentDefinition):
+                agent_defs[name] = agent_data
+            else:
+                # Reconstruct from dict
+                agent_defs[name] = AgentDefinition(
+                    description=agent_data.get('description', ''),
+                    prompt=agent_data.get('prompt', ''),
+                    tools=agent_data.get('tools'),
+                    model=agent_data.get('model'),
+                )
+
+    # Create hooks for streaming tool calls and subagent execution
+    hooks = create_streaming_hooks(
+        task_id=task_id,
+        trace_id=trace_id,
+        parent_span_id=parent_span_id,
+    )
+
+    # Configure Claude with workspace isolation, session resume, subagents, and hooks
+    options = ClaudeAgentOptions(
+        cwd=workspace_path,
+        allowed_tools=allowed_tools,
+        permission_mode=permission_mode,  # type: ignore
+        system_prompt=system_prompt,
+        resume=resume_session_id,
+        agents=agent_defs,
+        hooks=hooks,  # Tool lifecycle hooks for streaming!
+    )
+
+    # Create message handler for streaming
+    handler = ClaudeMessageHandler(
+        task_id=task_id,
+        trace_id=trace_id,
+        parent_span_id=parent_span_id,
+    )
+
+    # Run Claude and process messages
+    try:
+        await handler.initialize()
+
+        async with ClaudeSDKClient(options=options) as client:
+            await client.query(prompt)
+
+            # Use receive_response() instead of receive_messages()
+            # receive_response() yields messages until ResultMessage, then stops
+            # receive_messages() is infinite and never completes!
+            async for message in client.receive_response():
+                await handler.handle_message(message)
+
+        logger.debug(f"Message loop completed, cleaning up...")
+        await handler.cleanup()
+
+        results = handler.get_results()
+        logger.debug(f"Returning results with keys: {results.keys()}")
+        return results
+
+    except Exception as e:
+        logger.error(f"[run_claude_agent_activity] Error: {e}", exc_info=True)
+        await handler.cleanup()
+        raise

agentex/lib/core/temporal/plugins/claude_agents/hooks/__init__.py

@@ -0,0 +1,11 @@
+"""Claude SDK hooks for streaming lifecycle events to AgentEx UI."""
+
+from agentex.lib.core.temporal.plugins.claude_agents.hooks.hooks import (
+    TemporalStreamingHooks,
+    create_streaming_hooks,
+)
+
+__all__ = [
+    "create_streaming_hooks",
+    "TemporalStreamingHooks",
+]