feat: expose run step budgets to clients

src/wf_cli/commands/runs.py

@@ -70,6 +70,14 @@ def start_run(
             "--trace-limit", min=1, max=100, help="Optional trace slice limit."
         ),
     ] = None,
+    max_steps: Annotated[
+        int | None,
+        typer.Option(
+            "--max-steps",
+            min=1,
+            help="Optional run step budget; the server default applies when omitted.",
+        ),
+    ] = None,
 ) -> None:
     """Start one workflow deployment."""
     try:
@@ -84,6 +92,7 @@ def start_run(
             deployment_id=deployment_id,
             workflow_input=workflow_input,
             trace_range=trace_range,
+            max_steps=max_steps,
         ),
     )
     emit_json(payload)

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:

src/wf_transport_rpc_http/client/runs.py

@@ -36,17 +36,18 @@ class RpcRunClientMixin:
         deployment_id: str,
         workflow_input: dict[str, Any],
         trace_range: TraceRangeLike | None = None,
+        max_steps: int | None = None,
     ) -> RunResult:
+        params: dict[str, Any] = {
+            "deployment_id": deployment_id,
+            "workflow_input": workflow_input,
+            "trace_range": _trace_range_payload(trace_range),
+        }
+        if max_steps is not None:
+            params["max_steps"] = max_steps
         return cast(
             RunResult,
-            await self._call(
-                "workflow.runs.start",
-                {
-                    "deployment_id": deployment_id,
-                    "workflow_input": workflow_input,
-                    "trace_range": _trace_range_payload(trace_range),
-                },
-            ),
+            await self._call("workflow.runs.start", params),
         )
 
     async def resume_run(

src/wf_transport_rpc_http/methods/runs.py

@@ -52,6 +52,7 @@ def register_methods(
                     if params.trace_range is not None
                     else None
                 ),
+                max_steps=params.max_steps,
             )
         except (ValueError, KeyError, LookupError, FileNotFoundError) as exc:
             raise_workflow_rpc_error(exc)

src/wf_transport_rpc_http/models.py

@@ -435,6 +435,14 @@ class StartRunParams(RpcParamsModel):
     deployment_id: str = Field(min_length=1)
     workflow_input: dict[str, Any] = Field(default_factory=dict)
     trace_range: TraceRangeParams | None = None
+    max_steps: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Optional run step budget. The server default applies when omitted; "
+            "resume never accepts a replacement."
+        ),
+    )
 
 
 class InspectRunParams(RpcParamsModel):