velophex 0.2.0__py3-none-any.whl

velophex/runtime/client.py

@@ -0,0 +1,957 @@
+"""HTTP client for the Orchestrator Runtime API (``/api/v1/runtime/*``).
+
+The client is built from the ``start`` context and nothing else. In particular the execution
+token (``vpx_rt_…``) is **never** read from the environment and never written to one: it
+authorises this attempt only, it is revoked the moment the attempt ends, and a token that
+reaches a child process or a log line has left the blast radius the platform designed for it
+(``docs/runner-sdk-protocol.md`` section 3.3).
+
+Every call is already scoped to one attempt by the token, so no method names a tenant, a
+workspace or a job.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from datetime import UTC, datetime
+from typing import IO, Any, Final, NoReturn
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from velophex import _json
+from velophex.contracts.executor import FAULT_ENVELOPE_VERSION, FaultInfo
+from velophex.contracts.runtimes import FaultKinds
+from velophex.errors import VelophexError
+from velophex.runtime.models import (
+    ActionAppSchema,
+    ActionTaskResult,
+    AddQueueItemRequest,
+    CancellationState,
+    QueueItem,
+    ResolvedSecret,
+    RuntimeActionTask,
+    RuntimeAsset,
+    RuntimeContext,
+    RuntimeCredential,
+    RuntimeJob,
+    RuntimeQueue,
+    StartedJob,
+    StorageFile,
+    StorageFileList,
+)
+
+__all__ = [
+    "ACTION_TASKS_CAPABILITY",
+    "RUNTIME_API_PATH",
+    "STORAGE_BUCKETS_CAPABILITY",
+    "ActionAppNotFoundError",
+    "ActionHubDisabledError",
+    "ActionHubError",
+    "ActionHubRuntimeUnsupportedError",
+    "ActionTaskCorrelationConflictError",
+    "ActionTaskInputInvalidError",
+    "ActionTaskNotFoundError",
+    "ActionTaskNotOwnedError",
+    "ActionTaskTimeoutError",
+    "AgentsNotEnabledError",
+    "AiBudgetExhaustedError",
+    "AiError",
+    "AiPolicyDeniedError",
+    "AiProviderUnavailableError",
+    "AiRequestInvalidError",
+    "RuntimeApiError",
+    "RuntimeClient",
+    "StorageBucketsUnsupportedError",
+    "runtime_base_url",
+    "runtime_error",
+]
+
+RUNTIME_API_PATH: Final = "/api/v1/runtime"
+
+_DEFAULT_TIMEOUT: Final = httpx.Timeout(30.0, connect=10.0)
+
+#: The runtime capability of the action-task routes (``GET /runtime/capabilities``).
+ACTION_TASKS_CAPABILITY: Final = "action-tasks/1"
+
+#: The runtime capability of the storage bucket routes (``RuntimeCapabilities.StorageBuckets``).
+STORAGE_BUCKETS_CAPABILITY: Final = "storage-buckets/1"
+
+#: Transport timeout of one upload or download: a file may be 100 MiB.
+_FILE_TIMEOUT: Final = httpx.Timeout(300.0, connect=10.0)
+
+#: The server holds one wait at most this long (``ActionTaskLimits.MaxWaitSeconds``).
+_MAX_WAIT_SECONDS: Final = 25
+
+#: Transport timeout of one wait: the server cap plus ten seconds (plan X3).
+_WAIT_TIMEOUT: Final = httpx.Timeout(_MAX_WAIT_SECONDS + 10.0, connect=10.0)
+
+#: Transient failures of one wait retried before giving up (1, 2, 4, 8, 16 s apart).
+_WAIT_RETRIES: Final = 5
+
+
+class RuntimeApiError(VelophexError):
+    """The Runtime API refused a call.
+
+    :attr:`status_code` and :attr:`problem` carry the RFC 9457 problem details the Orchestrator
+    returns, so an automation can tell ``no_capable_runner`` from a transport failure. The error
+    envelope (code, cause, fix, request id, retry scope, docs URL) is read from the same problem.
+    """
+
+    def __init__(self, status_code: int, problem: dict[str, Any] | None, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.problem = problem or {}
+
+    @property
+    def code(self) -> str | None:
+        """The Orchestrator's machine-readable error code, when it sent one."""
+        return self._text("code")
+
+    @property
+    def cause(self) -> str | None:
+        """Why it happened, in one line."""
+        return self._text("cause")
+
+    @property
+    def fix(self) -> str | None:
+        """What to do about it."""
+        return self._text("fix")
+
+    @property
+    def request_id(self) -> str | None:
+        """The Orchestrator's id of the refused request."""
+        return self._text("requestId") or self._text("traceId")
+
+    @property
+    def retry_scope(self) -> str | None:
+        """What a retry would repeat: ``none``, ``model-call`` or ``run``."""
+        return self._text("retryScope")
+
+    @property
+    def docs_url(self) -> str | None:
+        """The reference page of :attr:`code`."""
+        return self._text("docsUrl")
+
+    @property
+    def retryable(self) -> bool:
+        """Whether sending the same call again could succeed."""
+        value = self.problem.get("retryable")
+        return value if isinstance(value, bool) else self.status_code == 0 or self.status_code >= 500
+
+    def to_fault(self) -> FaultInfo | None:
+        """A refusal with a code is reported under that code; a bare transport failure is not."""
+        if self.code is None:
+            return None
+
+        infrastructure = self.status_code == 0 or self.status_code >= 500
+
+        return FaultInfo(
+            kind=FaultKinds.INFRASTRUCTURE if infrastructure else FaultKinds.APPLICATION,
+            code=self.code,
+            message=str(self),
+            retryable=self.retryable,
+            version=FAULT_ENVELOPE_VERSION,
+            cause=self.cause or self._text("detail"),
+            fix=self.fix,
+            retry_scope=self.retry_scope,
+            request_id=self.request_id,
+            docs_url=self.docs_url,
+        )
+
+    def _text(self, name: str) -> str | None:
+        value = self.problem.get(name)
+        return value if isinstance(value, str) else None
+
+
+class ActionHubError(RuntimeApiError):
+    """An Action Hub refusal, named by its catalogue code (``docs/action-hub.md``).
+
+    :attr:`fix` is what to do about it, and :attr:`retryable` whether the same call could succeed.
+    """
+
+    @property
+    def retryable(self) -> bool:
+        """Whether sending the same call again could succeed."""
+        return self.problem.get("retryable") is True
+
+
+class AiError(RuntimeApiError):
+    """A refusal of the LLM gateway, named by its ``ai_*`` code."""
+
+
+class AiBudgetExhaustedError(AiError):
+    """``ai_budget_exhausted``: the workspace's AI budget is spent."""
+
+
+class AiPolicyDeniedError(AiError):
+    """``ai_policy_denied``: the workspace's AI policy refused the call."""
+
+
+class AiProviderUnavailableError(AiError):
+    """``ai_provider_unavailable``: the provider failed after the gateway's retries."""
+
+
+class AiRequestInvalidError(AiError):
+    """``ai_request_invalid``: the call is invalid, e.g. a model that is not a binding."""
+
+
+class AgentsNotEnabledError(AiError):
+    """``agents_not_enabled`` or ``agentic_feature_off``: an administrator turns Agents on."""
+
+
+class ActionHubDisabledError(ActionHubError):
+    """``action_hub_disabled``: the tenant has not enabled Action Hub."""
+
+
+class ActionAppNotFoundError(ActionHubError):
+    """``action_app_not_found`` or ``action_app_version_not_published``."""
+
+
+class ActionTaskInputInvalidError(ActionHubError):
+    """``action_task_input_invalid``: :attr:`errors` pins each problem by JSON Pointer."""
+
+    @property
+    def errors(self) -> list[dict[str, Any]]:
+        """``[{code, path, message}]``, one per problem."""
+        value = self.problem.get("errors")
+        return value if isinstance(value, list) else []
+
+
+class ActionTaskCorrelationConflictError(ActionHubError):
+    """``action_task_correlation_conflict``: the key was used with a different payload."""
+
+
+class ActionTaskNotFoundError(ActionHubError):
+    """``action_task_not_found``."""
+
+
+class ActionTaskNotOwnedError(ActionHubError):
+    """``action_task_not_owned_by_job``: a job reads only the tasks it created."""
+
+
+class ActionHubRuntimeUnsupportedError(ActionHubError):
+    """``action_hub_runtime_unsupported``: the Orchestrator predates Action Hub automation."""
+
+
+class ActionTaskTimeoutError(ActionHubError):
+    """The wait ran out with ``raise_on_timeout=True``. The task stays open."""
+
+
+class StorageBucketsUnsupportedError(RuntimeApiError):
+    """The Orchestrator predates storage buckets (no ``storage-buckets/1`` capability)."""
+
+
+_AI_ERRORS: Final[dict[str, type[AiError]]] = {
+    "ai_budget_exhausted": AiBudgetExhaustedError,
+    "ai_policy_denied": AiPolicyDeniedError,
+    "ai_provider_unavailable": AiProviderUnavailableError,
+    "ai_request_invalid": AiRequestInvalidError,
+    "agents_not_enabled": AgentsNotEnabledError,
+    "agentic_feature_off": AgentsNotEnabledError,
+}
+
+_ACTION_HUB_ERRORS: Final[dict[str, type[ActionHubError]]] = {
+    "action_hub_disabled": ActionHubDisabledError,
+    "action_app_not_found": ActionAppNotFoundError,
+    "action_app_version_not_published": ActionAppNotFoundError,
+    "action_task_input_invalid": ActionTaskInputInvalidError,
+    "action_task_correlation_conflict": ActionTaskCorrelationConflictError,
+    "action_task_not_found": ActionTaskNotFoundError,
+    "action_task_not_owned_by_job": ActionTaskNotOwnedError,
+    "action_hub_runtime_unsupported": ActionHubRuntimeUnsupportedError,
+}
+
+
+def runtime_base_url(orchestrator_url: str) -> str:
+    """Derive the Runtime API base from the URL the ``start`` context carries.
+
+    The Runner may pass the site root, the API base or the runtime base; all three appear in
+    ``docs/runner-sdk-protocol.md`` section 2 discovery. Normalising here keeps every caller
+    from guessing.
+    """
+    trimmed = orchestrator_url.rstrip("/")
+
+    if trimmed.endswith(RUNTIME_API_PATH):
+        return trimmed
+
+    if trimmed.endswith("/api/v1"):
+        return trimmed + "/runtime"
+
+    return trimmed + RUNTIME_API_PATH
+
+
+class RuntimeClient:
+    """Synchronous client for the Runtime API.
+
+    A handler declared ``async def`` should call it through :func:`asyncio.to_thread`: the
+    automation owns the process, so a blocking call costs nothing but a thread, and one HTTP
+    surface is easier to keep in step with the protocol than two.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: httpx.Timeout | float = _DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+        trace_parent: str | None = None,
+    ) -> None:
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+
+        if trace_parent:
+            headers["traceparent"] = trace_parent
+
+        self._capabilities: frozenset[str] | None = None
+        self._client = httpx.Client(
+            base_url=runtime_base_url(base_url),
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> RuntimeClient:
+        return self
+
+    def __exit__(self, *exception: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release the connection pool."""
+        self._client.close()
+
+    # ---------------------------------------------------------------- context
+
+    def context(self) -> RuntimeContext:
+        """Job, attempt, workspace, automation, entry point, inputs and deadline."""
+        return RuntimeContext.model_validate(self._request("GET", "/context"))
+
+    def cancellation(self) -> CancellationState:
+        """Whether a stop was requested for this attempt, and why."""
+        return CancellationState.model_validate(self._request("GET", "/cancellation"))
+
+    # ---------------------------------------------------------------- logs
+
+    def write_logs(self, entries: list[dict[str, Any]]) -> dict[str, Any]:
+        """Send a batch of log entries (at most 500, de-duplicated on sequence)."""
+        return self._request("POST", "/logs", body={"entries": entries}) or {}
+
+    # ---------------------------------------------------------------- assets
+
+    def asset(self, name: str) -> RuntimeAsset:
+        """Read an asset of the job's workspace, including its decrypted secret."""
+        return RuntimeAsset.model_validate(self._request("GET", f"/assets/{_segment(name)}"))
+
+    def set_asset(
+        self,
+        name: str,
+        *,
+        text: str | None = None,
+        integer: int | None = None,
+        boolean: bool | None = None,
+        secret: str | None = None,
+        user_name: str | None = None,
+        password: str | None = None,
+    ) -> None:
+        """Set the value of an asset the job's workspace owns."""
+        body = {
+            "text": text,
+            "integer": integer,
+            "boolean": boolean,
+            "secret": secret,
+            "userName": user_name,
+            "password": password,
+        }
+
+        self._request("PUT", f"/assets/{_segment(name)}", body={k: v for k, v in body.items() if v is not None})
+
+    def resolve_secret(self, name: str) -> ResolvedSecret:
+        """Resolve a secret asset, or ``"<credential>.password"`` for a credential's password."""
+        return ResolvedSecret.model_validate(self._request("POST", "/secrets/resolve", body={"name": name}))
+
+    def credential(self, name: str) -> RuntimeCredential:
+        """The account name of a credential asset. The password comes from :meth:`resolve_secret`."""
+        return RuntimeCredential.model_validate(self._request("GET", f"/credentials/{_segment(name)}"))
+
+    # ---------------------------------------------------------------- queues
+
+    def queue(self, name: str) -> RuntimeQueue:
+        """Queue metadata by name: retry budget, unique-reference flag and SLA."""
+        return RuntimeQueue.model_validate(self._request("GET", f"/queues/{_segment(name)}"))
+
+    def add_queue_item(self, queue: str, item: AddQueueItemRequest) -> QueueItem:
+        """Add an item to a queue of the job's workspace."""
+        body = item.model_dump(by_alias=True, exclude_none=True, mode="json")
+        return QueueItem.model_validate(self._request("POST", f"/queues/{_segment(queue)}/items", body=body))
+
+    def claim_queue_item(self, queue: str) -> QueueItem | None:
+        """Claim the next item, or ``None`` when the queue has nothing due."""
+        payload = self._request("POST", f"/queues/{_segment(queue)}/items/claim")
+        return QueueItem.model_validate(payload) if payload is not None else None
+
+    def complete_queue_item(self, item_id: UUID | str, output: Any | None = None) -> QueueItem:
+        """Mark an item successful."""
+        return QueueItem.model_validate(
+            self._request("POST", f"/queue-items/{item_id}/complete", body={"output": output})
+        )
+
+    def fail_queue_item(
+        self,
+        item_id: UUID | str,
+        *,
+        kind: str,
+        reason: str | None = None,
+        output: Any | None = None,
+    ) -> QueueItem:
+        """Mark an item failed. ``kind`` is ``Business`` (final) or ``Application`` (retried)."""
+        return QueueItem.model_validate(
+            self._request(
+                "POST",
+                f"/queue-items/{item_id}/fail",
+                body={"kind": kind, "reason": reason, "output": output},
+            )
+        )
+
+    def extend_queue_item_lease(self, item_id: UUID | str) -> QueueItem:
+        """Extend the lease of an item this attempt holds."""
+        return QueueItem.model_validate(self._request("POST", f"/queue-items/{item_id}/lease"))
+
+    def postpone_queue_item(
+        self,
+        item_id: UUID | str,
+        defer_until: datetime,
+        deadline: datetime | None = None,
+    ) -> QueueItem:
+        """Give an item back to the queue until *defer_until*, without spending a retry."""
+        body = {"deferUntil": defer_until.isoformat(), "deadline": deadline.isoformat() if deadline else None}
+        return QueueItem.model_validate(self._request("POST", f"/queue-items/{item_id}/postpone", body=body))
+
+    def report_queue_item_progress(self, item_id: UUID | str, progress: str | None) -> QueueItem:
+        """Record progress text on an item this attempt holds."""
+        return QueueItem.model_validate(
+            self._request("PUT", f"/queue-items/{item_id}/progress", body={"progress": progress})
+        )
+
+    # ---------------------------------------------------------------- child jobs
+
+    def start_job(
+        self,
+        *,
+        automation_id: UUID | str | None = None,
+        automation_name: str | None = None,
+        inputs: Any | None = None,
+        priority: int | None = None,
+    ) -> StartedJob:
+        """Start a child automation in the parent's own workspace.
+
+        The chain depth is bounded by the server (``Jobs:MaxChainDepth``); inputs are
+        validated against the child's entry point schema, so a bad call is ``422`` rather
+        than a job that fails on the robot.
+        """
+        body = {
+            "automationId": str(automation_id) if automation_id else None,
+            "automationName": automation_name,
+            "inputs": inputs,
+            "priority": priority,
+        }
+
+        return StartedJob.model_validate(self._request("POST", "/jobs", body=body))
+
+    def list_jobs(
+        self,
+        *,
+        automation_name: str | None = None,
+        statuses: list[str] | None = None,
+        top: int = 50,
+    ) -> list[RuntimeJob]:
+        """The newest jobs of this workspace (at most 100), optionally of one automation and in some statuses."""
+        params = {"top": str(max(1, min(top, 100)))}
+
+        if automation_name:
+            params["automationName"] = automation_name
+
+        if statuses:
+            params["status"] = ",".join(statuses)
+
+        answer = self._request("GET", "/jobs", params=params)
+
+        return [RuntimeJob.model_validate(item) for item in answer.get("items") or []]
+
+    def stop_job(self, job_id: UUID | str, *, kill: bool = False) -> None:
+        """Ask a job of this workspace to stop, or with ``kill`` end it at once; a pending job is canceled."""
+        self._request("POST", f"/jobs/{_segment(str(job_id))}/stop", body={"strategy": "Kill" if kill else "SoftStop"})
+
+    def raise_alert(self, message: str, *, severity: str = "Info") -> None:
+        """Raise an alert (``Info``, ``Warning`` or ``Error``): a workspace notification tied to this job."""
+        self._request("POST", "/alerts", body={"severity": severity, "message": message})
+
+    # ---------------------------------------------------------------- action tasks
+
+    def create_action_task(
+        self,
+        app_key: str,
+        version: int,
+        input: dict[str, Any] | None = None,
+        *,
+        correlation_key: str | None = None,
+        title: str | None = None,
+        assignee_user_id: UUID | str | None = None,
+        assignee_group: str | None = None,
+        due_at: datetime | None = None,
+        priority: str | None = None,
+    ) -> UUID:
+        """Raise an Action Hub task from ``app_key`` at a published ``version``; returns its id.
+
+        The input is validated against the version's input schema
+        (:class:`ActionTaskInputInvalidError`). With the same ``correlation_key`` and payload a
+        second call in this job returns the same task, so a retry never raises two.
+        """
+        self._ensure_action_tasks()
+
+        body = {
+            "appKey": app_key,
+            "version": version,
+            "title": title,
+            "input": input,
+            "correlationKey": correlation_key,
+            "assigneeUserId": str(assignee_user_id) if assignee_user_id else None,
+            "assigneeGroup": assignee_group,
+            "dueAt": due_at.isoformat() if due_at else None,
+            "priority": priority,
+        }
+
+        created = self._request("POST", "/action-tasks", body=body)
+        return UUID(str(created["taskId"]))
+
+    def get_action_task(self, task_id: UUID | str) -> RuntimeActionTask:
+        """The task's status, and its outcome and output once completed."""
+        self._ensure_action_tasks()
+        return RuntimeActionTask.model_validate(self._request("GET", f"/action-tasks/{task_id}"))
+
+    def wait_for_action_task(
+        self,
+        task_id: UUID | str,
+        *,
+        timeout: float = 900.0,
+        raise_on_timeout: bool = False,
+        deadline: datetime | None = None,
+        stop_requested: Any | None = None,
+    ) -> ActionTaskResult:
+        """Wait for the task's decision, one server long poll (at most 25 s) at a time.
+
+        Returns ``completed`` or ``canceled``; after ``timeout`` seconds (never past
+        ``deadline``) the task stays open and the result is ``timedOut``, or
+        :class:`ActionTaskTimeoutError` with ``raise_on_timeout=True``. ``stop_requested``, a
+        callable, ends the wait within one poll when it turns true. Transient failures are
+        retried with a bounded backoff. It always waits in the job: a Python job cannot suspend.
+        For waits of hours or days, use the app's continuation.
+        """
+        self._ensure_action_tasks()
+
+        answer = self._long_poll(
+            f"/action-tasks/{task_id}/wait",
+            ("completed", "canceled"),
+            _until(timeout, deadline),
+            stop_requested,
+            lambda error: isinstance(error, ActionHubError),
+        )
+
+        if answer is None:
+            if raise_on_timeout:
+                raise ActionTaskTimeoutError(0, None, f"Action task {task_id} was not decided in time; it stays open.")
+
+            return ActionTaskResult(taskId=task_id, status="timedOut")
+
+        return ActionTaskResult.model_validate(answer)
+
+    def action_app_schema(self, app_key: str, version: int) -> ActionAppSchema:
+        """The input and output JSON Schema of a published app version."""
+        self._ensure_action_tasks()
+        return ActionAppSchema.model_validate(
+            self._request("GET", f"/action-apps/{_segment(app_key)}/versions/{version}/schema")
+        )
+
+    # ---------------------------------------------------------------- agents
+
+    def agent_candidate(self, agent_key: str, candidate_id: str) -> dict[str, Any]:
+        """The immutable candidate an agent run executes: ``{agentKey, candidateId, definition, ...}``."""
+        return self._request("GET", f"/agents/{_segment(agent_key)}/candidates/{_segment(candidate_id)}")
+
+    def write_spans(self, spans: list[dict[str, Any]], trace_id: UUID | str | None = None) -> None:
+        """Record trace spans of this job (``traces/spans``)."""
+        self._request("POST", "/traces/spans", body={"traceId": str(trace_id) if trace_id else None, "spans": spans})
+
+    def search_vector_store(self, store: str, query: str, top_k: int | None = None) -> list[dict[str, Any]]:
+        """The closest documents of a workspace vector store: ``[{documentId, content, metadata, score}]``."""
+        answer = self._request("POST", f"/vector-stores/{_segment(store)}/search", body={"query": query, "topK": top_k})
+        return list((answer or {}).get("results") or [])
+
+    def call_mcp_tool(
+        self,
+        server: str,
+        tool: str,
+        payload: Any | None = None,
+        *,
+        idempotency_key: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> dict[str, Any]:
+        """Call a tool of a workspace MCP server: ``{success, data, error, statusCode, durationMs}``.
+
+        The same ``idempotency_key`` replays the first answer instead of calling the server twice.
+        """
+        return self._request(
+            "POST",
+            f"/mcp/servers/{_segment(server)}/call",
+            body={"toolName": tool, "payload": payload, "timeoutSeconds": timeout_seconds},
+            headers={"Idempotency-Key": idempotency_key} if idempotency_key else None,
+        )
+
+    def invoke_tool(
+        self, name: str, arguments: dict[str, Any], *, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
+        """Invoke a workspace tool by name: ``{success, tool, data, error, durationMs}``."""
+        return self._request(
+            "POST",
+            f"/tools/{_segment(name)}/invoke",
+            body=arguments,
+            headers={"Idempotency-Key": idempotency_key} if idempotency_key else None,
+        )
+
+    def request_tool_approval(
+        self,
+        *,
+        tool_name: str,
+        tool_kind: str,
+        tool_ref: str,
+        arguments: dict[str, Any],
+        idempotency_key: str,
+    ) -> dict[str, Any]:
+        """Ask a person to approve one tool call with its exact arguments: ``{approvalId, status}``.
+
+        The same ``idempotency_key`` returns the same approval, so a retried request never asks twice.
+        """
+        return self._request(
+            "POST",
+            "/agents/tool-approvals",
+            body={
+                "toolName": tool_name,
+                "toolKind": tool_kind,
+                "toolRef": tool_ref,
+                "arguments": arguments,
+                "idempotencyKey": idempotency_key,
+            },
+        )
+
+    def wait_for_tool_approval(
+        self,
+        approval_id: str,
+        *,
+        timeout: float,
+        deadline: datetime | None = None,
+        stop_requested: Any | None = None,
+    ) -> str:
+        """``approved``, ``rejected`` or ``expired``; ``timedOut`` when nobody decided within ``timeout``.
+
+        A bounded wait in the job, like :meth:`wait_for_action_task`: never past ``deadline``.
+        """
+        answer = self._long_poll(
+            f"/agents/tool-approvals/{_segment(approval_id)}/wait",
+            ("approved", "rejected", "expired"),
+            _until(timeout, deadline),
+            stop_requested,
+            lambda error: False,
+        )
+
+        return "timedOut" if answer is None else str(answer["status"])
+
+    def _long_poll(
+        self,
+        path: str,
+        finished: tuple[str, ...],
+        until: float,
+        stop_requested: Any | None,
+        final: Any,
+    ) -> dict[str, Any] | None:
+        """Poll ``path?timeoutSeconds=`` until its ``status`` is one of ``finished``; ``None`` at ``until``.
+
+        Transient failures are retried with a bounded backoff (1, 2, 4, 8, 16 s); a refusal the
+        caller calls ``final``, or any 4xx, is raised at once.
+        """
+        failures = 0
+
+        while True:
+            remaining = until - time.monotonic()
+
+            if remaining <= 0 or (stop_requested is not None and stop_requested()):
+                return None
+
+            seconds = int(min(remaining, _MAX_WAIT_SECONDS))
+
+            try:
+                answer = self._request("GET", f"{path}?timeoutSeconds={seconds}", timeout=_WAIT_TIMEOUT) or {}
+                failures = 0
+            except RuntimeApiError as error:
+                failures += 1
+
+                if final(error) or 0 < error.status_code < 500 or failures > _WAIT_RETRIES:
+                    raise
+
+                time.sleep(2 ** (failures - 1))
+                continue
+
+            if answer.get("status") in finished:
+                return answer
+
+    # ---------------------------------------------------------------- storage buckets
+
+    def list_files(
+        self,
+        bucket: str,
+        prefix: str | None = None,
+        *,
+        pattern: str | None = None,
+        recursive: bool = False,
+        cursor: str | None = None,
+    ) -> StorageFileList:
+        """One page of a bucket's files under ``prefix`` (the root when ``None``).
+
+        ``pattern`` is ``*``/``?`` wildcards on the file name, several separated by ``;``. Pass the
+        page's ``next_cursor`` as ``cursor`` for the next page; :meth:`iter_files` does that for you.
+        """
+        self._ensure_storage()
+
+        params: dict[str, str] = {"recursive": "true" if recursive else "false"}
+
+        for name, value in (("prefix", prefix), ("pattern", pattern), ("cursor", cursor)):
+            if value:
+                params[name] = value
+
+        return StorageFileList.model_validate(
+            self._request("GET", f"/storage-buckets/{_segment(bucket)}/files", params=params)
+        )
+
+    def iter_files(
+        self,
+        bucket: str,
+        prefix: str | None = None,
+        *,
+        pattern: str | None = None,
+        recursive: bool = False,
+    ) -> Iterator[StorageFile]:
+        """Every file of a listing, page after page."""
+        cursor: str | None = None
+
+        while True:
+            page = self.list_files(bucket, prefix, pattern=pattern, recursive=recursive, cursor=cursor)
+            yield from page.files
+
+            if not page.next_cursor:
+                return
+
+            cursor = page.next_cursor
+
+    def upload_file(
+        self,
+        bucket: str,
+        path: str,
+        content: bytes | IO[bytes],
+        *,
+        content_type: str | None = None,
+    ) -> StorageFile:
+        """Store ``content`` at ``path`` (a new version when the path exists in an internal bucket)."""
+        self._ensure_storage()
+
+        response = self._send(
+            "PUT",
+            f"/storage-buckets/{_segment(bucket)}/files/content",
+            params={"path": path},
+            content=content,
+            headers={"Content-Type": content_type or "application/octet-stream"},
+        )
+
+        return StorageFile.model_validate(_json.loads(response.content))
+
+    def download_file(self, bucket: str, path: str, destination: IO[bytes]) -> None:
+        """Copy a file's bytes into ``destination`` (an open binary file or buffer)."""
+        self._ensure_storage()
+
+        url = f"/storage-buckets/{_segment(bucket)}/files/content"
+
+        try:
+            with self._client.stream("GET", url, params={"path": path}, timeout=_FILE_TIMEOUT) as response:
+                if not response.is_success:
+                    response.read()
+                    _raise_for(response, "GET", url)
+
+                for chunk in response.iter_bytes():
+                    destination.write(chunk)
+        except httpx.HTTPError as error:
+            raise RuntimeApiError(0, None, f"The Runtime API could not be reached: {error}") from error
+
+    def read_file(self, bucket: str, path: str) -> bytes:
+        """A file's bytes."""
+        self._ensure_storage()
+
+        return self._send("GET", f"/storage-buckets/{_segment(bucket)}/files/content", params={"path": path}).content
+
+    def delete_file(self, bucket: str, path: str) -> None:
+        """Delete one file (``storage_file_not_found`` when there is none)."""
+        self._ensure_storage()
+        self._request("DELETE", f"/storage-buckets/{_segment(bucket)}/files", params={"path": path})
+
+    def _ensure_storage(self) -> None:
+        if STORAGE_BUCKETS_CAPABILITY not in self._capabilities_offered():
+            raise StorageBucketsUnsupportedError(
+                501,
+                {"code": "storage_buckets_runtime_unsupported"},
+                "The Orchestrator does not offer storage buckets "
+                f"(runtime capability {STORAGE_BUCKETS_CAPABILITY}); upgrade it.",
+            )
+
+    def _capabilities_offered(self) -> frozenset[str]:
+        """The server's runtime capabilities, asked once per client (plan X7)."""
+        if self._capabilities is None:
+            try:
+                capabilities = self._request("GET", "/capabilities") or {}
+                self._capabilities = frozenset(capabilities.get("capabilities") or [])
+            except RuntimeApiError as error:
+                if error.status_code != httpx.codes.NOT_FOUND:
+                    raise
+
+                # An Orchestrator that predates the capability route.
+                self._capabilities = frozenset()
+
+        return self._capabilities
+
+    def _ensure_action_tasks(self) -> None:
+        """Checks the server's action-task capability once per client (plan X7)."""
+        if ACTION_TASKS_CAPABILITY not in self._capabilities_offered():
+            raise ActionHubRuntimeUnsupportedError(
+                501,
+                {"code": "action_hub_runtime_unsupported"},
+                "The Orchestrator does not offer Action Hub automation (runtime capability "
+                f"{ACTION_TASKS_CAPABILITY}); upgrade it to a version in the Action Hub compatibility matrix.",
+            )
+
+    # ---------------------------------------------------------------- plumbing
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any | None = None,
+        timeout: httpx.Timeout | None = None,
+        params: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        content = None
+        headers = dict(headers or {})
+
+        if body is not None:
+            # The platform writer, not httpx's json=, so payloads escape like every other
+            # VeloPhex document and a datetime never sneaks through unformatted.
+            content = _json.encode_wire(_strip_none(body))
+            headers["Content-Type"] = "application/json"
+
+        try:
+            if timeout is None:
+                response = self._client.request(method, path, content=content, headers=headers, params=params)
+            else:
+                response = self._client.request(
+                    method, path, content=content, headers=headers, params=params, timeout=timeout
+                )
+        except httpx.HTTPError as error:
+            raise RuntimeApiError(0, None, f"The Runtime API could not be reached: {error}") from error
+
+        if response.status_code == httpx.codes.NO_CONTENT or not response.content:
+            if not response.is_success:
+                _raise_for(response, method, path)
+
+            return None
+
+        if response.is_success:
+            return _json.loads(response.content)
+
+        _raise_for(response, method, path)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str],
+        content: bytes | IO[bytes] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """A request whose body or answer is a file's bytes rather than a JSON document."""
+        try:
+            response = self._client.request(
+                method, path, params=params, content=content, headers=headers, timeout=_FILE_TIMEOUT
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeApiError(0, None, f"The Runtime API could not be reached: {error}") from error
+
+        if not response.is_success:
+            _raise_for(response, method, path)
+
+        return response
+
+
+def _raise_for(response: httpx.Response, method: str, path: str) -> NoReturn:
+    """Raise the typed error for a refused call, from its RFC 9457 problem details."""
+    problem = None
+
+    try:
+        parsed = _json.loads(response.content)
+        problem = parsed if isinstance(parsed, dict) else None
+    except ValueError:
+        problem = None
+
+    detail = (problem or {}).get("detail") or (problem or {}).get("title") or response.reason_phrase
+
+    raise runtime_error(response.status_code, problem, f"{method} {path} failed with {response.status_code}: {detail}")
+
+
+def runtime_error(status_code: int, problem: dict[str, Any] | None, message: str) -> RuntimeApiError:
+    """The typed error of a refusal: an Action Hub or AI gateway class by its ``code``, else the base."""
+    code = (problem or {}).get("code")
+    error_type: type[RuntimeApiError] = RuntimeApiError
+
+    if isinstance(code, str):
+        if _is_action_hub(code):
+            error_type = _ACTION_HUB_ERRORS.get(code, ActionHubError)
+        elif code in _AI_ERRORS:
+            error_type = _AI_ERRORS[code]
+        elif code.startswith("ai_"):
+            error_type = AiError
+
+    return error_type(status_code, problem, message)
+
+
+def _until(timeout: float, deadline: datetime | None) -> float:
+    """The monotonic instant a wait ends: ``timeout`` from now, and 30 s before ``deadline``."""
+    until = time.monotonic() + max(timeout, 0.0)
+
+    if deadline is not None:
+        until = min(until, time.monotonic() + (deadline - datetime.now(UTC)).total_seconds() - 30.0)
+
+    return until
+
+
+def _is_action_hub(code: str) -> bool:
+    return code.startswith("action_") or code in ("self_approval_forbidden", "continuation_start_failed")
+
+
+def _strip_none(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {name: _strip_none(member) for name, member in value.items() if member is not None}
+
+    return value
+
+
+def _segment(value: str) -> str:
+    """Percent-encode one path segment; asset and queue names may contain spaces."""
+    return quote(value, safe="")