mitos-run 0.1.0__py3-none-any.whl

mitos/__init__.py

@@ -0,0 +1,52 @@
+from mitos import guest
+from mitos.aio import AsyncAgentRun, AsyncSandbox
+from mitos.client import AgentRun
+from mitos.direct import DirectSandbox, SandboxServer, create
+from mitos.errors import (
+    AgentRunError,
+    ExecutionDeadlineError,
+    IdleTimeoutError,
+    NotFoundError,
+    RateLimitedError,
+    RequestCanceledError,
+    TimeoutTooLargeError,
+    UnauthorizedError,
+)
+from mitos.sandbox import Sandbox
+from mitos.template import Template
+from mitos.types import (
+    Execution,
+    ExecResult,
+    ExecutionError,
+    FileInfo,
+    ForkPolicy,
+    Network,
+    Result,
+)
+
+__all__ = [
+    "create",
+    "DirectSandbox",
+    "SandboxServer",
+    "AgentRun",
+    "AgentRunError",
+    "ExecutionDeadlineError",
+    "IdleTimeoutError",
+    "NotFoundError",
+    "RateLimitedError",
+    "RequestCanceledError",
+    "TimeoutTooLargeError",
+    "UnauthorizedError",
+    "AsyncAgentRun",
+    "AsyncSandbox",
+    "Sandbox",
+    "Template",
+    "ExecResult",
+    "Execution",
+    "ExecutionError",
+    "Result",
+    "FileInfo",
+    "ForkPolicy",
+    "Network",
+    "guest",
+]

mitos/_envelope.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from mitos.errors import AgentRunError, error_for_code
+
+
+def _redact(text: str, token: Optional[str]) -> str:
+    """Replaces every occurrence of a non-empty token with [REDACTED]. Mirrors
+    the TypeScript redact helper and internal/mcp redaction."""
+    if not token:
+        return text
+    return text.replace(token, "[REDACTED]")
+
+
+# Default code and remediation per HTTP status, used when the body is not the
+# structured server envelope (an older server, a proxy 502, a transport layer).
+_STATUS_CODE = {
+    400: "bad_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    409: "conflict",
+    413: "request_too_large",
+    429: "rate_limited",
+    500: "internal_error",
+    503: "unavailable",
+}
+
+_STATUS_REMEDIATION = {
+    401: "Check the sandbox bearer token is set and authorizes this sandbox.",
+    403: "Check the sandbox bearer token is set and authorizes this sandbox.",
+    404: "Confirm the sandbox id exists and is Ready before calling.",
+    413: "Reduce the request payload size (file content is hex-encoded and bounded by the server).",
+    429: "Back off and retry the request after a short delay.",
+}
+
+
+def _status_code(status: int) -> str:
+    if status in _STATUS_CODE:
+        return _STATUS_CODE[status]
+    return "server_error" if status >= 500 else "request_failed"
+
+
+def _status_remediation(status: int) -> str:
+    if status in _STATUS_REMEDIATION:
+        return _STATUS_REMEDIATION[status]
+    if status >= 500:
+        return "Retry the request; if it persists, inspect the forkd or sandbox-server logs."
+    return "Inspect the request fields against the sandbox API contract."
+
+
+def error_from_response(resp: httpx.Response, token: Optional[str] = None) -> AgentRunError:
+    """Builds an AgentRunError from a non-2xx response. Prefers the structured
+    server envelope {error:{code,message,cause,remediation}}; falls back to
+    status-derived defaults for an older or non-mitos server. Any bearer token
+    echoed in the body is redacted before it becomes the cause."""
+    status = resp.status_code
+    body_text = _redact(resp.text, token)
+
+    code = _status_code(status)
+    message = f"sandbox API request failed: HTTP {status} ({code})"
+    cause = body_text.strip() or f"HTTP {status}"
+    remediation = _status_remediation(status)
+    context: dict = {}
+
+    try:
+        parsed = resp.json()
+    except Exception:  # noqa: BLE001  not JSON; keep the text fallback
+        parsed = None
+
+    if isinstance(parsed, dict):
+        err = parsed.get("error")
+        if isinstance(err, dict):
+            # New structured envelope.
+            code = err.get("code") or code
+            message = err.get("message") or message
+            cause = _redact(err.get("cause", ""), token) or cause
+            remediation = err.get("remediation") or remediation
+            ctx = err.get("context")
+            if isinstance(ctx, dict):
+                context = ctx
+        elif isinstance(err, str):
+            # Legacy bare {"error": "msg"} shape.
+            cause = _redact(err, token) or cause
+
+    # Build the TYPED subclass for the code (issue #216): a caller branches on
+    # the exception type, never on the message. An unknown code falls back to the
+    # base AgentRunError inside error_for_code.
+    return error_for_code(
+        code,
+        message,
+        cause=cause,
+        remediation=remediation,
+        status=status,
+        context=context,
+    )
+
+
+def raise_for_status(resp: httpx.Response, token: Optional[str] = None) -> None:
+    """Raises AgentRunError on a non-2xx response, leaving 2xx untouched. Drop-in
+    for httpx Response.raise_for_status() but yields the structured type."""
+    if resp.is_success:
+        return
+    raise error_from_response(resp, token=token)
+
+
+def raise_for_status_stream(resp: httpx.Response, token: Optional[str] = None) -> None:
+    """Like raise_for_status, for a streaming Response whose body has not been
+    read. On a non-2xx status it reads the (small) error body so the structured
+    envelope can be parsed; on success it leaves the stream unread so the caller
+    iterates it normally."""
+    if resp.is_success:
+        return
+    resp.read()
+    raise error_from_response(resp, token=token)

mitos/_k8s.py

@@ -0,0 +1,69 @@
+"""Lazy accessor for the optional ``kubernetes`` client (issue #22).
+
+The cluster-mode modules (``client``, ``aio``, ``sandbox``, ``workspace``) need
+the official Kubernetes client, but direct mode (``mitos.direct`` over the
+sandbox-server REST API) and the in-guest SDK (``mitos.guest``) speak only
+httpx and must import with no Kubernetes installed. To keep ``import mitos`` and
+``from mitos.direct import SandboxServer`` light, those modules import the
+``kubernetes`` symbols through :func:`k8s` at the moment a cluster code path
+runs, never at module import time. This mirrors the TypeScript SDK, whose
+``@kubernetes/client-node`` is lazy-loaded so direct mode never pulls it in.
+
+A missing ``kubernetes`` raises a clear, actionable AgentRunError naming the
+install command, rather than a bare ModuleNotFoundError from deep in an import.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mitos.errors import AgentRunError
+
+if TYPE_CHECKING:
+    # Annotation-only imports: TYPE_CHECKING is False at runtime, so these never
+    # force the kubernetes import for callers that only use direct mode.
+    from kubernetes import client as _client_mod
+    from kubernetes import config as _config_mod
+    from kubernetes.client.rest import ApiException as _ApiException
+
+
+class _K8s:
+    """The three kubernetes symbols the cluster modules use, bound lazily."""
+
+    __slots__ = ("client", "config", "ApiException")
+
+    def __init__(self, client, config, ApiException):
+        self.client = client
+        self.config = config
+        self.ApiException = ApiException
+
+
+_cached: "_K8s | None" = None
+
+
+def k8s() -> "_K8s":
+    """Import and return the kubernetes client/config/ApiException, cached.
+
+    Called only from cluster code paths. If the optional ``kubernetes`` package
+    is not installed, raises an AgentRunError that names the fix instead of
+    letting a raw ModuleNotFoundError surface from an unexpected place."""
+    global _cached
+    if _cached is not None:
+        return _cached
+    try:
+        from kubernetes import client as k8s_client
+        from kubernetes import config as k8s_config
+        from kubernetes.client.rest import ApiException
+    except ModuleNotFoundError as exc:
+        raise AgentRunError(
+            "cluster mode requires the kubernetes client, which is not installed",
+            code="kubernetes_not_installed",
+            cause=f"importing the kubernetes package failed: {exc}",
+            remediation=(
+                "Install it with 'pip install kubernetes' or 'pip install mitos-run[k8s]'. "
+                "Direct mode (mitos.create / mitos.direct) and the in-guest SDK "
+                "(mitos.guest) do not need it."
+            ),
+        ) from exc
+    _cached = _K8s(k8s_client, k8s_config, ApiException)
+    return _cached