feat: expose run step budgets to clients

src/wf_client/_http_port.py

@@ -259,6 +259,7 @@ class PublicErrorWorkflowClientPort:
         deployment_id: str,
         workflow_input: dict[str, Any],
         trace_range: TraceRangeLike | None = None,
+        max_steps: int | None = None,
     ) -> RunResult:
         return await self._invoke(
             "workflow.runs.start",
@@ -266,6 +267,7 @@ class PublicErrorWorkflowClientPort:
             deployment_id=deployment_id,
             workflow_input=workflow_input,
             trace_range=trace_range,
+            max_steps=max_steps,
         )
 
     async def inspect_run(self, *, run_id: str) -> RunResult:

src/wf_client/codec.py

@@ -51,6 +51,9 @@ class _DecodedRunFields:
     error: str | None
     output: dict[str, Any] | None
     trace_count: int
+    max_steps: int
+    steps_executed: int
+    steps_remaining: int
     diagnostics: tuple[DependencyDiagnostic, ...]
     next_actions: dict[str, Any]
     trace: tuple[dict[str, Any], ...] | None = None
@@ -255,6 +258,9 @@ def _decode_run_fields(
         error=wire["error"],
         output=dict(wire["output"]) if wire["output"] is not None else None,
         trace_count=wire["trace_count"],
+        max_steps=wire["max_steps"],
+        steps_executed=wire["steps_executed"],
+        steps_remaining=wire["steps_remaining"],
         diagnostics=diagnostics,
         next_actions=dict(wire["next_actions"]),
         trace=trace,
@@ -269,7 +275,12 @@ def decode_run_result(
     *,
     operation: str = "workflow.runs.inspect",
 ) -> DecodedRunResult:
-    """Validate and decode a start/inspect/resume run response."""
+    """Validate and decode a start/inspect/resume run response.
+
+    ``RunResult`` declares the ``max_steps``/``steps_executed``/
+    ``steps_remaining`` trio as required, so a response missing any of them
+    fails validation here instead of reaching client reconstruction.
+    """
     wire = _validate(payload, RunResult, operation)
     fields = _decode_run_fields(
         wire,

src/wf_client/deployments.py

@@ -179,17 +179,27 @@ class Deployment:
             diagnostics=diagnostics,
         )
 
-    async def run(self, workflow_input: Mapping[str, Any]) -> Run:
+    async def run(
+        self,
+        workflow_input: Mapping[str, Any],
+        *,
+        max_steps: int | None = None,
+    ) -> Run:
         from .codec import decode_run_result
         from .runs import _run_from_decoded
 
-        decoded = decode_run_result(
-            await self._port.run_deployment(
+        if max_steps is None:
+            raw = await self._port.run_deployment(
                 deployment_id=self.deployment_id,
                 workflow_input=dict(workflow_input),
-            ),
-            operation="workflow.runs.start",
-        )
+            )
+        else:
+            raw = await self._port.run_deployment(
+                deployment_id=self.deployment_id,
+                workflow_input=dict(workflow_input),
+                max_steps=max_steps,
+            )
+        decoded = decode_run_result(raw, operation="workflow.runs.start")
         if decoded.deployment_id != self.deployment_id:
             raise InvalidResponse(
                 operation="workflow.runs.start",

src/wf_client/protocols.py

@@ -121,6 +121,7 @@ class WorkflowClientPort(Protocol):
         deployment_id: str,
         workflow_input: dict[str, Any],
         trace_range: TraceRangeLike | None = None,
+        max_steps: int | None = None,
     ) -> RunResult: ...
 
     async def list_runs(

src/wf_client/runs.py

@@ -119,12 +119,21 @@ def _run_from_decoded(
         interrupt=_interrupt(decoded.interrupt, operation=operation),
         diagnostics=decoded.diagnostics,
         trace_count=decoded.trace_count,
+        max_steps=decoded.max_steps,
+        steps_executed=decoded.steps_executed,
+        steps_remaining=decoded.steps_remaining,
     )
 
 
 @dataclass(frozen=True, slots=True, init=False)
 class Run:
-    """Immutable client snapshot of one durable deployment run."""
+    """Immutable client snapshot of one durable deployment run.
+
+    ``max_steps``, ``steps_executed``, and ``steps_remaining`` are the
+    server-effective budget values returned with every run response. The
+    server substitutes its default limit when creation omits one, so
+    refresh/resume reconstruction simply preserves whatever was returned.
+    """
 
     _port: WorkflowClientPort = field(repr=False, compare=False)
     run_id: str
@@ -135,6 +144,9 @@ class Run:
     _interrupt: InterruptRequest | None = field(repr=False)
     _diagnostics: tuple[DependencyDiagnostic, ...] = field(repr=False)
     trace_count: int
+    max_steps: int
+    steps_executed: int
+    steps_remaining: int
 
     def __init__(
         self,
@@ -148,6 +160,9 @@ class Run:
         interrupt: InterruptRequest | None,
         diagnostics: tuple[DependencyDiagnostic, ...],
         trace_count: int,
+        max_steps: int,
+        steps_executed: int,
+        steps_remaining: int,
     ) -> None:
         object.__setattr__(self, "_port", _port)
         object.__setattr__(self, "run_id", run_id)
@@ -162,6 +177,9 @@ class Run:
             tuple(item.model_copy(deep=True) for item in diagnostics),
         )
         object.__setattr__(self, "trace_count", trace_count)
+        object.__setattr__(self, "max_steps", max_steps)
+        object.__setattr__(self, "steps_executed", steps_executed)
+        object.__setattr__(self, "steps_remaining", steps_remaining)
 
     @property
     def output(self) -> dict[str, Any] | None: