vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/api/endpoints/runtime.py

@@ -0,0 +1,113 @@
+"""Typed HTTP operations for local-runtime discovery and paid admission.
+
+No execution input crosses this boundary. The future executor will call admission only
+after it knows that a supported native host can actually be launched.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ....types.runtime import (
+    RuntimeAdmissionGrant as AdmissionGrant,
+)
+from ....types.runtime import (
+    RuntimeAdmissionRequest as AdmissionRequest,
+)
+from ....types.runtime import (
+    RuntimeCapabilityCatalog,
+    RuntimeGrantVerificationRequest,
+)
+from ..client import ApiClient
+from ..response import ResponseDecoder, ResponseShape
+
+if TYPE_CHECKING:
+    from ..runtime_payment import RuntimePayment
+
+RUNTIME_CATALOG_PATH = "/api/x402/runtime"
+ADVERSARIAL_TEAM_ADMISSION_PATH = "/api/x402/runtime/adversarial-team/admissions"
+# Matches the capability declared in the backend x402 catalog (vidbyte PR #508), which
+# names these routes "activate" rather than "admissions".
+SAME_HOST_ENSEMBLE_ADMISSION_PATH = "/api/x402/runtime/same-host-ensemble/activate"
+PERSISTENCE_ADMISSION_PATH = "/api/x402/runtime/persistence/activate"
+TASK_BOARD_ADMISSION_PATH = "/api/x402/runtime/task-board/activate"
+STAGES_ADMISSION_PATH = "/api/x402/runtime/stages/admissions"
+
+
+class RuntimeEndpoints:
+    """Runtime operations bound to one authenticated API client."""
+
+    def __init__(self, client: ApiClient) -> None:
+        # Retains the invocation-owned client without opening a connection.
+        self._client = client
+
+    def verify_grant(self, request: RuntimeGrantVerificationRequest) -> AdmissionGrant:
+        # Authenticates the proof at the server without exposing its HMAC signing secret.
+        return self._client.post(
+            "/api/x402/runtime/grants/verify", request, AdmissionGrant, shape=ResponseShape.DIRECT
+        )
+
+    def list_capabilities(self) -> RuntimeCapabilityCatalog:
+        # Reads the direct runtime-only catalog document.
+        return self._client.get(
+            RUNTIME_CATALOG_PATH, RuntimeCapabilityCatalog, shape=ResponseShape.DIRECT
+        )
+
+    def admit_adversarial_team(self, request: AdmissionRequest, key: str) -> AdmissionGrant:
+        # Purchases one replay-safe local execution admission.
+        return self._client.post(
+            ADVERSARIAL_TEAM_ADMISSION_PATH,
+            request,
+            AdmissionGrant,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=key,
+        )
+
+    def admit_same_host_ensemble(self, request: AdmissionRequest, key: str) -> AdmissionGrant:
+        # Purchases one replay-safe local execution admission.
+        return self._client.post(
+            SAME_HOST_ENSEMBLE_ADMISSION_PATH,
+            request,
+            AdmissionGrant,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=key,
+        )
+
+    def admit_persistence_x402(
+        self, request: AdmissionRequest, key: str, payer: RuntimePayment
+    ) -> AdmissionGrant:
+        # The same receipt goes through database-backed online verification before launch.
+        response = self._client.post_runtime_payment(
+            PERSISTENCE_ADMISSION_PATH, request, key, payer
+        )
+        return ResponseDecoder().one(response, AdmissionGrant, ResponseShape.DIRECT)
+
+    def admit_persistence(self, request: AdmissionRequest, key: str) -> AdmissionGrant:
+        # Purchases one replay-safe local execution admission.
+        return self._client.post(
+            PERSISTENCE_ADMISSION_PATH,
+            request,
+            AdmissionGrant,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=key,
+        )
+
+    def admit_task_board(self, request: AdmissionRequest, key: str) -> AdmissionGrant:
+        # Purchases one replay-safe local task-board admission.
+        return self._client.post(
+            TASK_BOARD_ADMISSION_PATH,
+            request,
+            AdmissionGrant,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=key,
+        )
+
+    def admit_stages(self, request: AdmissionRequest, key: str) -> AdmissionGrant:
+        # Purchases one replay-safe local stages admission at the one-cent floor.
+        return self._client.post(
+            STAGES_ADMISSION_PATH,
+            request,
+            AdmissionGrant,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=key,
+        )

vidbyte_cli/lib/api/problem.py

@@ -0,0 +1,86 @@
+"""One HTTP failure status in, one typed CliError out.
+
+Classification reads the status code and the `x-request-id` header, and nothing else. The
+response body is never parsed: failure prose in this CLI is static authored text, and a
+backend body may quote a prompt, a credential, or another account's content.
+
+The arms are split more finely than the status families suggest, because the remedies
+differ. 401 means log in, 403 means grant a scope, 429 means poll less often, and a 409 on
+this surface always means the same thing about continuing a run.
+"""
+
+from __future__ import annotations
+
+import httpx
+from pydantic import JsonValue, ValidationError
+
+from ...types.api import ApiUsageExhaustedProblem
+from ..errors.cli_error import CliError
+from ..errors.failures import (
+    ApiCredentialsRejected,
+    ApiCreditExhausted,
+    ApiOperationFailed,
+    ApiPermissionDenied,
+    ApiRateLimited,
+    ApiRequestConflicted,
+    ApiRequestRejected,
+    ApiResourceNotFound,
+    ApiRouteMissing,
+    ApiUnavailable,
+    ApiUnreachable,
+)
+from .response import ResponseDecoder
+
+
+class ApiProblemMapper:
+    """Status-driven, body-free classification of backend failures."""
+
+    def from_response(
+        self,
+        response: httpx.Response,
+        *,
+        route_not_found: bool = False,
+    ) -> CliError:
+        # Maps one non-success status onto the failure whose hint actually resolves it.
+        request_id = ResponseDecoder.request_id(response)
+        status = response.status_code
+        match status:
+            case 401:
+                return ApiCredentialsRejected(request_id)
+            case 403:
+                return ApiPermissionDenied(request_id)
+            case 402:
+                return ApiCreditExhausted(request_id, self._usage_remediation(response))
+            case 404:
+                if route_not_found:
+                    return ApiRouteMissing(request_id)
+                return ApiResourceNotFound(request_id)
+            case 409:
+                return ApiRequestConflicted(request_id)
+            case 400 | 422:
+                return ApiRequestRejected(request_id)
+            case 429:
+                return ApiRateLimited(request_id, self._retry_after(response))
+            case _ if status >= 500:
+                return ApiUnavailable(request_id)
+            case _:
+                return ApiOperationFailed(request_id)
+
+    def from_transport(self, error: httpx.HTTPError) -> CliError:
+        # No response ever arrived, so there is no status and no request ID to report.
+        return ApiUnreachable(error)
+
+    def _retry_after(self, response: httpx.Response) -> int | None:
+        # The authored rate-limit hint may repeat only a bounded numeric delta.
+        value = response.headers.get("retry-after", "").strip()
+        return int(value) if value.isdigit() else None
+
+    def _usage_remediation(self, response: httpx.Response) -> dict[str, JsonValue] | None:
+        # Only the bounded, allowlisted exhaustion contract may influence CLI output.
+        if len(response.content) > 32_768:
+            return None
+        try:
+            problem = ApiUsageExhaustedProblem.model_validate_json(response.content)
+        except (ValidationError, ValueError):
+            return None
+        return problem.remediation.model_dump(mode="json")

vidbyte_cli/lib/api/response.py

@@ -0,0 +1,101 @@
+"""What a backend route's success body looks like, and the only decoder that reads one.
+
+Routes disagree about their envelope: the research surface returns its DTO directly, while
+the older public resources wrap it in `{success, data}`. The shape is therefore declared per
+route by the endpoint group rather than assumed here, so adding a route cannot silently
+unwrap something that was never wrapped.
+
+Every rejection is the same failure on purpose. A caller cannot act differently on a wrong
+content type than on a schema mismatch, and telling them apart would mean quoting the body.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from ..errors.failures import ApiResponseUnsupported
+
+if TYPE_CHECKING:
+    import httpx
+
+TModel = TypeVar("TModel", bound=BaseModel)
+# Bounds a hostile or misrouted response before it is parsed into memory.
+_MAX_RESPONSE_BYTES = 1_048_576
+
+
+class ResponseShape(StrEnum):
+    """How a route wraps the payload a caller actually wants.
+
+    The research surface returns its DTO directly; the older public resources wrap it in
+    `{success, data}`. Every route declares which, so adding one cannot silently unwrap
+    something that was never wrapped.
+    """
+
+    DIRECT = "direct"
+    ENVELOPE = "envelope"
+
+
+class ResponseDecoder:
+    """Bounded validation from an HTTP success response into typed models."""
+
+    def one(
+        self,
+        response: httpx.Response,
+        model: type[TModel],
+        shape: ResponseShape,
+    ) -> TModel:
+        # Decodes a single record, unwrapping the envelope only when the route declares one.
+        payload = self._payload(response)
+        if shape is not ResponseShape.DIRECT:
+            payload = self._unwrap(response, payload)
+        try:
+            return model.model_validate(payload)
+        except ValidationError as error:
+            raise self._unsupported(response, error) from error
+
+    def _payload(self, response: httpx.Response) -> object:
+        # Content type and both size bounds are checked before any parsing happens.
+        if response.status_code == 204:
+            raise self._unsupported(response)
+        content_type = response.headers.get("content-type", "").split(";", 1)[0].lower()
+        if content_type != "application/json" and not content_type.endswith("+json"):
+            raise self._unsupported(response)
+        # A chunked response declares no length, so the materialized body is bounded too.
+        declared = response.headers.get("content-length")
+        if declared is not None and declared.isdigit() and int(declared) > _MAX_RESPONSE_BYTES:
+            raise self._unsupported(response)
+        content = response.content
+        if not content or len(content) > _MAX_RESPONSE_BYTES:
+            raise self._unsupported(response)
+        try:
+            return json.loads(content)
+        except (UnicodeError, json.JSONDecodeError) as error:
+            raise self._unsupported(response, error) from error
+
+    def _unwrap(self, response: httpx.Response, payload: object) -> object:
+        # The `{success, data}` wrapper the older public resources return.
+        if not isinstance(payload, dict) or payload.get("success") is False:
+            raise self._unsupported(response)
+        data = payload.get("data")
+        if data is None:
+            raise self._unsupported(response)
+        return data
+
+    def _unsupported(
+        self,
+        response: httpx.Response,
+        cause: Exception | None = None,
+    ) -> ApiResponseUnsupported:
+        return ApiResponseUnsupported(self.request_id(response), cause)
+
+    @staticmethod
+    def request_id(response: httpx.Response) -> str | None:
+        # A correlation header, never a body field: only headers are safe to echo back.
+        value = response.headers.get("x-request-id")
+        if value is None or not 1 <= len(value) <= 128:
+            return None
+        return str(value)

vidbyte_cli/lib/api/retry.py

@@ -0,0 +1,116 @@
+"""Whether one failed attempt may be repeated, and how long to wait first.
+
+Kept apart from the client so the rule is readable on its own: retrying a mutation is only
+safe while an idempotency key makes the backend collapse duplicates, and every research
+mutation is priced. A `POST` without that key is therefore never repeated, whatever failed.
+
+This class decides; it never sleeps. The caller owns the wait, so the decision stays pure
+apart from injected randomness.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import random
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+import httpx
+
+_MAX_ATTEMPTS = 3
+_MAXIMUM_DELAY_SECONDS = 10.0
+_BASE_DELAY_SECONDS = 0.25
+_UNJITTERED_CAP_SECONDS = 4.0
+_JITTER_SECONDS = 0.25
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+_RETRYABLE_STATUSES = frozenset({408, 429, 502, 503, 504})
+_RETRYABLE_ERRORS = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.ReadTimeout,
+    httpx.RemoteProtocolError,
+)
+
+
+@dataclass(frozen=True)
+class RequestMetadata:
+    """The two facts about a request that decide whether repeating it is safe."""
+
+    method: str
+    has_idempotency_key: bool = False
+
+
+# One attempt ends as exactly one of these, which is why they travel as a union rather than
+# as a pair of nullable arguments nobody can see are mutually exclusive.
+RequestOutcome = httpx.Response | httpx.HTTPError
+
+
+@dataclass(frozen=True)
+class RetryDecision:
+    """One verdict, plus the wait the caller should perform before the next attempt."""
+
+    retry: bool
+    delay_seconds: float = 0.0
+    delay_clamped: bool = False
+
+
+class RetryPolicy:
+    """Bounded safe-retry policy with exponential backoff and jitter."""
+
+    def __init__(self, random_source: random.Random | None = None) -> None:
+        # Randomness is injected so jitter can be made deterministic by a caller.
+        self._random = random_source or random.Random()
+
+    def decide(
+        self,
+        request: RequestMetadata,
+        attempt: int,
+        outcome: RequestOutcome,
+    ) -> RetryDecision:
+        # Answers whether this attempt may be repeated, and after how long.
+        if attempt >= _MAX_ATTEMPTS or not self._is_repeatable(request):
+            return RetryDecision(False)
+        if not self._is_transient(outcome):
+            return RetryDecision(False)
+        return self._delay(attempt, outcome)
+
+    def _is_repeatable(self, request: RequestMetadata) -> bool:
+        # A priced mutation may only be repeated while a key makes the backend deduplicate.
+        method = request.method.upper()
+        return method in _SAFE_METHODS or (method == "POST" and request.has_idempotency_key)
+
+    def _is_transient(self, outcome: RequestOutcome) -> bool:
+        # Distinguishes a failure worth repeating from a rejection that will repeat itself.
+        if isinstance(outcome, httpx.Response):
+            return outcome.status_code in _RETRYABLE_STATUSES
+        return isinstance(outcome, _RETRYABLE_ERRORS)
+
+    def _delay(self, attempt: int, outcome: RequestOutcome) -> RetryDecision:
+        # A server's own pacing wins over the local curve, up to the local ceiling.
+        server_delay = self._retry_after(outcome)
+        if server_delay is not None:
+            clamped = server_delay > _MAXIMUM_DELAY_SECONDS
+            return RetryDecision(True, min(server_delay, _MAXIMUM_DELAY_SECONDS), clamped)
+        backoff = min(_BASE_DELAY_SECONDS * (2 ** (attempt - 1)), _UNJITTERED_CAP_SECONDS)
+        jittered = backoff + self._random.uniform(0.0, _JITTER_SECONDS)
+        return RetryDecision(True, min(jittered, _MAXIMUM_DELAY_SECONDS))
+
+    def _retry_after(self, outcome: RequestOutcome) -> float | None:
+        # Accepts both header forms; an unparseable value is ignored rather than read as 0.
+        if not isinstance(outcome, httpx.Response):
+            return None
+        value = outcome.headers.get("retry-after")
+        if value is None:
+            return None
+        try:
+            return max(0.0, float(value))
+        except ValueError:
+            return self._retry_after_date(value)
+
+    def _retry_after_date(self, value: str) -> float | None:
+        # An HTTP-date already in the past yields no wait rather than a negative one.
+        try:
+            parsed = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        return max(0.0, (parsed.astimezone(UTC) - datetime.now(UTC)).total_seconds())

vidbyte_cli/lib/api/runtime_payment.py

@@ -0,0 +1,89 @@
+"""Explicit, bounded x402 authorization for one runtime admission.
+
+The API client owns HTTP and retries. This object validates the challenge and signs
+once; it never funds a wallet, launches an agent, or logs payment credentials.
+"""
+
+from collections.abc import Mapping
+from urllib.parse import urlsplit
+
+import httpx
+from eth_account import Account
+from eth_utils.address import is_address
+from x402 import x402ClientSync
+from x402.http import x402HTTPClientSync
+from x402.mechanisms.evm.constants import NETWORK_CONFIGS
+from x402.mechanisms.evm.exact import register_exact_evm_client
+from x402.schemas import PaymentRequired, PaymentRequirements
+
+from ..constants.runtime import RuntimePaymentConfig as Config
+from ..errors.failures import RuntimePaymentFailed
+
+
+class RuntimePayment:
+    """Invocation-owned signer with an exact price and allowed network."""
+
+    def __init__(self, environment: Mapping[str, str], cents: int) -> None:
+        # Validate opt-in credentials before sending the admission request.
+        self._network = environment.get(Config.NETWORK_ENV, Config.DEFAULT_NETWORK)
+        self._cents = cents
+        self._signed = False
+        if self._network not in Config.NETWORKS or cents <= 0:
+            raise RuntimePaymentFailed("configuration_invalid")
+        try:
+            signer = Account.from_key(environment.get(Config.PRIVATE_KEY_ENV, ""))
+            client = register_exact_evm_client(x402ClientSync(), signer, self._network)
+            self._http = x402HTTPClientSync(client)
+        except Exception as error:
+            raise RuntimePaymentFailed("signer_unavailable") from error
+
+    def headers(self, response: httpx.Response) -> dict[str, str]:
+        # Never create another authorization after a paid attempt fails or times out.
+        if self._signed:
+            raise RuntimePaymentFailed("authorization_already_created")
+        header = response.headers.get("PAYMENT-REQUIRED", "")
+        if not header or len(header) > Config.MAX_CHALLENGE_CHARACTERS:
+            raise RuntimePaymentFailed("challenge_missing_or_oversized")
+        try:
+            required = self._http.get_payment_required_response(response.headers.get)
+            self._validate(required, str(response.request.url))
+            self._signed = True
+            payload = self._http.create_payment_payload(required)
+            return self._http.encode_payment_signature_header(payload)
+        except RuntimePaymentFailed:
+            raise
+        except Exception as error:
+            raise RuntimePaymentFailed("challenge_or_signing_failed") from error
+
+    def _validate(self, required: object, url: str) -> None:
+        # Bind the authorization to the requested origin/resource and one reviewed exact price.
+        if not isinstance(required, PaymentRequired) or required.x402_version != 2:
+            raise RuntimePaymentFailed("protocol_invalid")
+        if required.resource is None or len(required.accepts) != 1:
+            raise RuntimePaymentFailed("resource_or_options_invalid")
+        resource, requested = urlsplit(required.resource.url), urlsplit(url)
+        if resource.scheme or resource.netloc:
+            matches = resource == requested
+        else:
+            matches = (
+                resource.path == requested.path and not resource.query and not resource.fragment
+            )
+        if not matches:
+            raise RuntimePaymentFailed("resource_mismatch")
+        self._validate_requirement(required.accepts[0])
+
+    def _validate_requirement(self, item: PaymentRequirements) -> None:
+        # Canonical six-decimal USDC and EIP-712 metadata prevent arbitrary-token authorization.
+        asset = NETWORK_CONFIGS[self._network]["default_asset"]
+        expected = str(self._cents * Config.MICROUNITS_PER_CENT)
+        if item.network != self._network or item.scheme != "exact" or item.amount != expected:
+            raise RuntimePaymentFailed("price_or_network_mismatch")
+        if item.asset.lower() != asset["address"].lower():
+            raise RuntimePaymentFailed("asset_mismatch")
+        extra = item.extra or {}
+        if extra.get("name") != asset["name"] or extra.get("version") != asset["version"]:
+            raise RuntimePaymentFailed("token_domain_mismatch")
+        if not is_address(item.pay_to) or int(item.pay_to, 16) == 0:
+            raise RuntimePaymentFailed("recipient_invalid")
+        if not 0 < item.max_timeout_seconds <= Config.MAX_AUTHORIZATION_SECONDS:
+            raise RuntimePaymentFailed("authorization_duration_invalid")

vidbyte_cli/lib/auth/__init__.py

@@ -0,0 +1,16 @@
+"""Secret-safe credential resolution and storage contracts."""
+
+from .credentials import Credentials, CredentialStorage, CredentialStore
+from .resolver import CredentialResolver, CredentialSource, ResolvedCredential
+from .verifier import ApiCredentialVerifier, CredentialVerifier
+
+__all__ = [
+    "ApiCredentialVerifier",
+    "CredentialResolver",
+    "CredentialSource",
+    "CredentialStorage",
+    "CredentialStore",
+    "CredentialVerifier",
+    "Credentials",
+    "ResolvedCredential",
+]