more updates to docs

Signed-off-by: Filinto Duran <[email protected]>

Author: filintod

README.md

@@ -186,7 +186,7 @@ See the [examples](./examples) directory for a list of sample orchestrations and
 - `async_fanout_fanin.py` - Updated to use new `durabletask.aio` package  
 - `async_enhanced_features.py` - Comprehensive demo of all enhanced features
 - `async_non_determinism_demo.py` - Non-determinism detection demonstration
-- See [ASYNC_ENHANCEMENTS.md](./ASYNC_ENHANCEMENTS.md) for detailed examples and usage patterns
+- See [ASYNC_ENHANCEMENTS.md](./durabletask/aio/ASYNCIO_ENHANCEMENTS.md) for detailed examples and usage patterns
 
 ## Development
 
@@ -264,7 +264,7 @@ Optional sandbox mode (`best_effort` or `strict`) patches `asyncio.sleep`, `rand
 
 In `strict` mode, `asyncio.create_task` is blocked inside workflows to preserve determinism and will raise a `SandboxViolationError` if used.
 
-> **Enhanced Sandbox Features**: The enhanced version includes comprehensive non-determinism detection, timeout support, enhanced concurrency primitives, and debugging tools. See [ASYNC_ENHANCEMENTS.md](./ASYNC_ENHANCEMENTS.md) for complete documentation.
+> **Enhanced Sandbox Features**: The enhanced version includes comprehensive non-determinism detection, timeout support, enhanced concurrency primitives, and debugging tools. See [ASYNC_ENHANCEMENTS.md](./durabletask/aio/ASYNCIO_ENHANCEMENTS.md) for complete documentation.
 
 #### Async patterns
 

codegen-requirements.txt

@@ -0,0 +1,2 @@
+grpcio-tools==1.62.3 # codegen only; conflicts with protobuf>=6 at runtime
+

ASYNC_ENHANCEMENTS.md renamed to durabletask/aio/ASYNCIO_ENHANCEMENTS.md

@@ -257,29 +257,3 @@ async def workflow_with_cleanup(ctx, input_data):
    ```bash
    export DAPR_WF_DEBUG=true
    ```
-
-## Compatibility
-
-- **Backward Compatible**: All existing async workflows continue to work
-- **Upstream Compatible**: Async enhancements live under `durabletask.aio`
-- **Zero Overhead**: Default behavior has no performance impact
-- **Opt-in Features**: Enhanced features are opt-in via `sandbox_mode`
-
-## Files Added/Modified
-
-### New Files
-- `tests/durabletask/test_asyncio_compat_enhanced.py` - Comprehensive tests
-- `tests/durabletask/test_non_determinism_detection.py` - Detection tests
-- `examples/async_enhanced_features.py` - Full feature demo
-- `examples/async_non_determinism_demo.py` - Detection demo
-- `examples/README_ENHANCED.md` - Detailed documentation
-- `ASYNC_ENHANCEMENTS.md` - This file
-
-### Modified Files
-- `durabletask/aio/*` - Async package with enhanced features
-- `README.md` - Updates to reference enhancements
-
-### Unchanged Files
-- `durabletask/task.py` - No changes to core task system
-- `durabletask/worker.py` - Minimal changes for async orchestrator registration
-- `durabletask/client.py` - No changes to client API

ASYNCIO_INTERNALS.md renamed to durabletask/aio/ASYNCIO_INTERNALS.md

@@ -33,7 +33,7 @@
 from .compatibility import OrchestrationContextProtocol, ensure_compatibility
 
 # Core context and driver
-from .context import AsyncWorkflowContext
+from .context import AsyncWorkflowContext, WorkflowInfo
 from .driver import CoroutineOrchestratorRunner, WorkflowFunction
 
 # Sandbox and error handling
@@ -56,6 +56,7 @@
 __all__ = [
     # Core classes
     "AsyncWorkflowContext",
+    "WorkflowInfo",
     "CoroutineOrchestratorRunner",
     "WorkflowFunction",
 

durabletask/aio/__init__.py

@@ -12,6 +12,7 @@
 from __future__ import annotations
 
 import os
+from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import Any, Callable, Dict, List, Optional, TypeVar, Union, cast
 
@@ -36,6 +37,27 @@
 T = TypeVar("T")
 
 
+@dataclass(frozen=True)
+class WorkflowInfo:
+    """
+    Read-only metadata snapshot about the running workflow execution.
+    
+    Similar to Temporal's workflow.info, this provides convenient access to
+    workflow execution metadata in a single immutable object.
+    """
+    instance_id: str
+    workflow_name: Optional[str]
+    is_replaying: bool
+    is_suspended: bool
+    parent_instance_id: Optional[str]
+    current_time: datetime
+    history_event_sequence: int
+    trace_parent: Optional[str]
+    trace_state: Optional[str]
+    orchestration_span_id: Optional[str]
+    workflow_attempt: Optional[int]
+
+
 @ensure_compatibility
 class AsyncWorkflowContext(DeterministicContextMixin):
     """
@@ -143,6 +165,32 @@ def workflow_attempt(self) -> Optional[int]:
         """Temporary: retry attempt for this workflow if available (propagated by worker)."""
         return getattr(self._base_ctx, 'workflow_attempt', None)
 
+    @property
+    def info(self) -> WorkflowInfo:
+        """
+        Get a read-only snapshot of workflow execution metadata.
+        
+        This provides a Temporal-style info object bundling instance_id, workflow_name,
+        is_replaying, timestamps, tracing info, and other metadata in a single immutable object.
+        Useful for deterministic logging, idempotency keys, and conditional logic based on replay state.
+        
+        Returns:
+            WorkflowInfo: Immutable dataclass with workflow execution metadata
+        """
+        return WorkflowInfo(
+            instance_id=self.instance_id,
+            workflow_name=self.workflow_name,
+            is_replaying=self.is_replaying,
+            is_suspended=self.is_suspended,
+            parent_instance_id=self.parent_instance_id,
+            current_time=self.current_utc_datetime,
+            history_event_sequence=self.history_event_sequence,
+            trace_parent=self.trace_parent,
+            trace_state=self.trace_state,
+            orchestration_span_id=self.orchestration_span_id,
+            workflow_attempt=self.workflow_attempt,
+        )
+    
     # Activity operations
     def activity(
         self,