feat: add get_custom_status() API and bump to duroxide 0.1.20

- Add get_custom_status() to OrchestrationContext for reading custom status
  within orchestrations (returns str or None)
- Bump duroxide to 0.1.20, duroxide-pg to 0.1.22
- Bump package version to 0.1.9 (pyproject.toml), crate to 0.1.8
- Add e2e tests: basic get/set across turns + CAN boundary persistence
- Update CHANGELOG.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: affandar

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2026-02-21
+
+### Added
+- **`ctx.get_custom_status()`** — read the current custom status value from within an orchestration. Returns the status string or `None` if none has been set. Reflects all `set_custom_status`/`reset_custom_status` calls, including across turn boundaries and continue-as-new.
+
+### Changed
+- Upgraded duroxide to 0.1.20, duroxide-pg to 0.1.22
+
 ## [0.1.8] - 2026-02-15
 
 ### Added

Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "duroxide-python"
-version = "0.1.7"
+version = "0.1.8"
 edition = "2021"
 
 [lib]
 name = "duroxide_python"
 crate-type = ["cdylib"]
 
 [dependencies]
-duroxide = { version = "0.1.19", features = ["sqlite"] }
-duroxide-pg = "0.1.21"
+duroxide = { version = "0.1.20", features = ["sqlite"] }
+duroxide-pg = "0.1.22"
 pyo3 = { version = "0.23", features = ["extension-module"] }
 async-trait = "0.1"
 tokio = { version = "1", features = ["full"] }

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "duroxide"
-version = "0.1.8"
+version = "0.1.9"
 description = "Python SDK for the Duroxide durable execution runtime"
 readme = "README.md"
 license = { text = "MIT" }

python/duroxide/__init__.py

@@ -26,6 +26,7 @@
     orchestration_trace_log,
     orchestration_set_custom_status,
     orchestration_reset_custom_status,
+    orchestration_get_custom_status,
     activity_is_cancelled,
     init_tracing,
 )

python/duroxide/context.py

@@ -9,11 +9,13 @@
 """
 
 import json
+from typing import Optional
 
 from duroxide._duroxide import (
     orchestration_trace_log,
     orchestration_set_custom_status,
     orchestration_reset_custom_status,
+    orchestration_get_custom_status,
     activity_trace_log,
     activity_is_cancelled,
 )
@@ -240,6 +242,15 @@ def reset_custom_status(self):
         """
         orchestration_reset_custom_status(self.instance_id)
 
+    def get_custom_status(self) -> Optional[str]:
+        """Read the current custom status value.
+
+        Returns the status string or None if none has been set.
+        Reflects all set/reset calls made so far, including across turns
+        and continue-as-new boundaries.
+        """
+        return orchestration_get_custom_status(self.instance_id)
+
     # ─── Logging (fire-and-forget, delegates to Rust ctx.trace()) ───
 
     def trace_info(self, message: str):

src/handlers.rs

@@ -128,6 +128,12 @@ pub fn orchestration_reset_custom_status(instance_id: &str) {
     }
 }
 
+/// Called from Python to read the current custom status from the OrchestrationContext.
+pub fn orchestration_get_custom_status(instance_id: &str) -> Option<String> {
+    let map = ORCHESTRATION_CTXS.lock().unwrap();
+    map.get(instance_id).and_then(|ctx| ctx.get_custom_status())
+}
+
 // ─── Activity Bridge ─────────────────────────────────────────────
 
 /// Wraps a Python callable as a Rust ActivityHandler.

src/lib.rs

@@ -42,6 +42,13 @@ fn orchestration_reset_custom_status(instance_id: String) {
     handlers::orchestration_reset_custom_status(&instance_id);
 }
 
+/// Read the current custom status value from an orchestration context.
+/// Returns None if no custom status has been set.
+#[pyfunction]
+fn orchestration_get_custom_status(instance_id: String) -> Option<String> {
+    handlers::orchestration_get_custom_status(&instance_id)
+}
+
 /// Get a Client from the stored ActivityContext (for use in activities).
 #[pyfunction]
 fn activity_get_client(token: String) -> Option<client::PyClient> {
@@ -111,6 +118,7 @@ fn _duroxide(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(activity_is_cancelled, m)?)?;
     m.add_function(wrap_pyfunction!(orchestration_set_custom_status, m)?)?;
     m.add_function(wrap_pyfunction!(orchestration_reset_custom_status, m)?)?;
+    m.add_function(wrap_pyfunction!(orchestration_get_custom_status, m)?)?;
     m.add_function(wrap_pyfunction!(activity_get_client, m)?)?;
     m.add_function(wrap_pyfunction!(init_tracing, m)?)?;
     m.add_class::<provider::PySqliteProvider>()?;

tests/test_e2e.py

@@ -756,7 +756,110 @@ def client_from_activity(ctx, input):
         runtime.shutdown(100)
 
 
-# ─── 26. Metrics Snapshot ───────────────────────────────────────
+# ─── 26. Custom Status Get ──────────────────────────────────────
+
+
+def test_custom_status_get_reflects_set_across_turns(provider):
+    """ctx.get_custom_status() returns correct value, including across turn boundaries."""
+    client = Client(provider)
+    runtime = Runtime(provider, PyRuntimeOptions(dispatcher_poll_interval_ms=50))
+
+    @runtime.register_activity("Echo")
+    def echo(ctx, input):
+        return input
+
+    @runtime.register_orchestration("GetterTest")
+    def getter_test(ctx, input):
+        # Before any set, should be None
+        assert ctx.get_custom_status() is None, "initial should be None"
+
+        ctx.set_custom_status("step-1")
+        assert ctx.get_custom_status() == "step-1", "should reflect set immediately"
+
+        # Cross a turn boundary
+        yield ctx.schedule_activity("Echo", "ping")
+
+        # After replay, should still return "step-1"
+        assert ctx.get_custom_status() == "step-1", "should survive replay across turns"
+
+        ctx.set_custom_status("step-2")
+        assert ctx.get_custom_status() == "step-2", "should reflect second set"
+
+        return "done"
+
+    runtime.start()
+    try:
+        instance_id = uid("cs-getter")
+        client.start_orchestration(instance_id, "GetterTest", "")
+        result = client.wait_for_orchestration(instance_id, 10_000)
+        assert result.status == "Completed"
+        assert result.output == "done"
+        assert result.custom_status == "step-2"
+    finally:
+        runtime.shutdown(100)
+
+
+def test_custom_status_persists_across_continue_as_new(provider):
+    """Custom status persists across CAN boundaries and can be reset."""
+    client = Client(provider)
+    runtime = Runtime(provider, PyRuntimeOptions(dispatcher_poll_interval_ms=50))
+
+    @runtime.register_activity("Echo")
+    def echo(ctx, input):
+        return input
+
+    @runtime.register_orchestration("StatusCanTest")
+    def status_can_test(ctx, input):
+        generation = input.get("generation", 1) if isinstance(input, dict) else 1
+
+        if generation == 1:
+            # First generation: set status, verify, then CAN
+            assert ctx.get_custom_status() is None, "gen1: initial should be None"
+            ctx.set_custom_status("gen1-active")
+            assert ctx.get_custom_status() == "gen1-active", "gen1: should reflect set"
+
+            # Cross a turn boundary to ensure persistence
+            yield ctx.schedule_activity("Echo", "ping")
+            assert ctx.get_custom_status() == "gen1-active", "gen1: should survive turn"
+
+            # CAN — runtime carries forward custom status automatically
+            yield ctx.continue_as_new({"generation": 2})
+            return None
+        elif generation == 2:
+            # Second generation: status should be carried forward from gen1
+            assert ctx.get_custom_status() == "gen1-active", "gen2: should inherit from gen1"
+
+            # Update status in gen2
+            ctx.set_custom_status("gen2-updated")
+            assert ctx.get_custom_status() == "gen2-updated", "gen2: should reflect new set"
+
+            # Now reset it
+            ctx.reset_custom_status()
+            assert ctx.get_custom_status() is None, "gen2: should be None after reset"
+
+            # CAN again with no status
+            yield ctx.continue_as_new({"generation": 3})
+            return None
+        else:
+            # Third generation: status should be None (was reset before CAN)
+            assert ctx.get_custom_status() is None, "gen3: should be None after reset+CAN"
+
+            ctx.set_custom_status("gen3-final")
+            return "done"
+
+    runtime.start()
+    try:
+        instance_id = uid("cs-can")
+        client.start_orchestration(instance_id, "StatusCanTest", {"generation": 1})
+        result = client.wait_for_orchestration(instance_id, 15_000)
+        assert result.status == "Completed"
+        assert result.output == "done"
+        assert result.custom_status == "gen3-final"
+    finally:
+        runtime.shutdown(100)
+
+
+# ─── 27. Metrics Snapshot ───────────────────────────────────────
 
 
 def test_metrics_snapshot(provider):