genesis-sandbox-client-python 0.1.0__py3-none-any.whl

genesis_sandbox_client/control_probe.py

@@ -0,0 +1,119 @@
+"""只读控制前提查询；不把Docker配置事实当成工作负载隔离验收。"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import ProtocolError
+
+
+@dataclass(frozen=True)
+class RuntimeControlCapabilities:
+    available: bool
+    runtime_kind: str
+    supports_resource_limits: bool
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.available) is not bool
+            or type(self.supports_resource_limits) is not bool
+            or not isinstance(self.runtime_kind, str)
+            or self.runtime_kind not in {"docker", "runsc"}
+        ):
+            raise ProtocolError("invalid runtime control facts")
+
+
+def parse_control_capabilities(value: Any) -> RuntimeControlCapabilities:
+    allowed = {
+        "available",
+        "runtime_kind",
+        "default_runtime",
+        "available_runtimes",
+        "runtime_profiles",
+        "supported_task_types",
+        "supported_languages",
+        "supported_state_policies",
+        "queue",
+        "queue_snapshots",
+        "execd",
+        "supports_runsc",
+        "supports_network_none",
+        "supports_resource_limits",
+        "message",
+    }
+    required = {
+        "available",
+        "runtime_kind",
+        "default_runtime",
+        "available_runtimes",
+        "queue",
+        "execd",
+        "supports_runsc",
+        "supports_network_none",
+        "supports_resource_limits",
+    }
+    if not isinstance(value, dict) or not required.issubset(value) or set(value) - allowed:
+        raise ProtocolError("invalid runtime control capability fields")
+    for field in ("available", "supports_runsc", "supports_network_none", "supports_resource_limits"):
+        if type(value[field]) is not bool:
+            raise ProtocolError("invalid runtime control boolean")
+    if (
+        not isinstance(value["runtime_kind"], str)
+        or value["runtime_kind"] not in {"docker", "runsc"}
+        or not isinstance(value["default_runtime"], str)
+    ):
+        raise ProtocolError("invalid runtime control kind")
+    for field in ("available_runtimes", "supported_task_types", "supported_languages", "supported_state_policies"):
+        if field not in value:
+            continue
+        items = value[field]
+        if items is None and not value["available"] and field == "available_runtimes":
+            continue
+        if (
+            not isinstance(items, list)
+            or len(items) > 256
+            or any(not isinstance(item, str) or len(item) > 256 for item in items)
+        ):
+            raise ProtocolError("invalid runtime control list")
+    if not isinstance(value["queue"], dict) or not isinstance(value["execd"], dict):
+        raise ProtocolError("invalid runtime control components")
+    if set(value["execd"]) != {"command", "session", "files", "metrics"} or any(
+        type(item) is not bool for item in value["execd"].values()
+    ):
+        raise ProtocolError("invalid runtime control execd declaration")
+    # 明确只消费driver.Probe与store.Ping的前提事实；注册runtime与execd声明不是隔离证明。
+    return RuntimeControlCapabilities(value["available"], value["runtime_kind"], value["supports_resource_limits"])
+
+
+class RuntimeControlClientMixin:
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        deadline_seconds: float | None = None,
+    ) -> Any:
+        raise NotImplementedError
+
+    def get_runtime_control_capabilities(self, *, timeout_seconds: float = 10) -> RuntimeControlCapabilities:
+        if (
+            isinstance(timeout_seconds, bool)
+            or not isinstance(timeout_seconds, (int, float))
+            or not math.isfinite(timeout_seconds)
+            or not 0 < timeout_seconds <= 30
+        ):
+            raise ValueError("control probe timeout must be finite and at most 30 seconds")
+        # 即便是GET也只发送一次；整批readiness的截止时间不得被客户端重试累加。
+        return parse_control_capabilities(
+            self._request(
+                "GET",
+                "/v1/sandbox/capabilities",
+                timeout=timeout_seconds,
+                max_retries=1,
+                deadline_seconds=timeout_seconds,
+            )
+        )

genesis_sandbox_client/deadline_http.py

@@ -0,0 +1,96 @@
+"""控制探测专用绝对读取截止；不改变其他业务调用的传输语义。"""
+
+from __future__ import annotations
+
+import http.client
+import io
+import socket
+import time
+import urllib.request
+from typing import Any
+
+
+def _remaining(deadline: float) -> float:
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise TimeoutError("control probe deadline exceeded")
+    return remaining
+
+
+class _DeadlineReader(io.RawIOBase):
+    def __init__(self, raw: Any, connection: socket.socket, deadline: float) -> None:
+        super().__init__()
+        self.raw, self.connection, self.deadline = raw, connection, deadline
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, buffer: Any) -> int:
+        self.connection.settimeout(_remaining(self.deadline))
+        return self.raw.readinto(buffer)
+
+    def close(self) -> None:
+        try:
+            self.raw.close()
+        finally:
+            super().close()
+
+
+class _DeadlineSocket:
+    def __init__(self, connection: socket.socket, deadline: float) -> None:
+        self.connection, self.deadline = connection, deadline
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.connection, name)
+
+    def makefile(self, mode: str, buffering: int | None = None) -> io.BufferedReader:
+        if mode != "rb":
+            raise ValueError("control probe only supports binary response reads")
+        # 使用原socket的file引用：HTTPConnection关闭时响应体仍由原file持有。
+        raw = self.connection.makefile("rb", buffering=0)
+        return io.BufferedReader(_DeadlineReader(raw, self.connection, self.deadline))
+
+
+class _DeadlineHTTPConnection(http.client.HTTPConnection):
+    def __init__(self, *args: Any, deadline: float, **kwargs: Any) -> None:
+        self.deadline = deadline
+        super().__init__(*args, **kwargs)
+
+    def connect(self) -> None:
+        self.timeout = _remaining(self.deadline)
+        super().connect()
+        assert self.sock is not None
+        self.sock.settimeout(_remaining(self.deadline))
+        self.sock = _DeadlineSocket(self.sock, self.deadline)  # type: ignore[assignment]
+
+
+class _DeadlineHTTPSConnection(http.client.HTTPSConnection):
+    def __init__(self, *args: Any, deadline: float, **kwargs: Any) -> None:
+        self.deadline = deadline
+        super().__init__(*args, **kwargs)
+
+    def connect(self) -> None:
+        self.timeout = _remaining(self.deadline)
+        super().connect()
+        assert self.sock is not None
+        self.sock.settimeout(_remaining(self.deadline))
+        self.sock = _DeadlineSocket(self.sock, self.deadline)  # type: ignore[assignment]
+
+
+def deadline_urlopen(request: urllib.request.Request, timeout_seconds: float) -> Any:
+    from .client import _NoRedirect
+
+    deadline = time.monotonic() + timeout_seconds
+
+    class HTTP(urllib.request.HTTPHandler):
+        def http_open(self, req: Any) -> Any:
+            return self.do_open(lambda *args, **kwargs: _DeadlineHTTPConnection(
+                *args, deadline=deadline, **kwargs), req)
+
+    class HTTPS(urllib.request.HTTPSHandler):
+        def https_open(self, req: Any) -> Any:
+            return self.do_open(lambda *args, **kwargs: _DeadlineHTTPSConnection(
+                *args, deadline=deadline, **kwargs), req)
+
+    return urllib.request.build_opener(_NoRedirect(), HTTP(), HTTPS()).open(
+        request, timeout=_remaining(deadline))

genesis_sandbox_client/errors.py

@@ -0,0 +1,133 @@
+"""Typed exceptions exposed by the Genesis Sandbox Python SDK."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+class SandboxError(Exception):
+    """Base class for all SDK-originated errors."""
+
+
+class APIError(SandboxError):
+    """Structured error returned by the Sandbox Service."""
+
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        message: str,
+        *,
+        request_id: str = "",
+        details: dict[str, Any] | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message
+        self.request_id = request_id
+        self.details = details or {}
+        self.retry_after = retry_after
+        super().__init__(
+            f"sandbox API {error_code or status_code} "
+            f"(status={status_code}, request_id={request_id or 'unknown'}): {message}"
+        )
+
+    @property
+    def retryable(self) -> bool:
+        value = self.details.get("retryable")
+        if isinstance(value, bool):
+            return value
+        return self.status_code == 429 or self.status_code >= 500
+
+
+class TransportError(SandboxError):
+    """Network or protocol failure before a valid API response was received."""
+
+
+class ProtocolError(TransportError):
+    """服务端返回了无法按契约解析的响应（如非法 JSON）。
+
+    继承 TransportError 以保持既有 except TransportError 调用方兼容；
+    classify_error 将其归类为 "protocol" 而不是 "transport"。
+    """
+
+
+class ExecRecoveryError(SandboxError):
+    """An exec may still be running; use its operation identity to resume observation.
+
+    ``phase`` 语义（Adapter 依赖稳定取值）：
+    - ``submit``：提交请求结果未知，远端执行可能已启动，须按 operation_id 查回执。
+    - ``observe``：观察回执失败，执行状态未确认，保持原 operation_id 继续观察。
+    - ``lookup``：按 operation_id 查回执失败，结果未知。
+    - ``cancel``：取消后停止未确认（stop unknown）。终态与停止确认是两件事；
+      未确认停止前不得回收资源或再次提交替代执行，须先按 operation_id 核对。
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        operation_id: str,
+        *,
+        exec_id: str | None = None,
+        phase: str,
+        cause: BaseException | None = None,
+    ) -> None:
+        self.session_id = session_id
+        self.operation_id = operation_id
+        self.exec_id = exec_id
+        self.phase = phase
+        self.cause = cause
+        identity = f"session_id={session_id}, operation_id={operation_id}"
+        if exec_id:
+            identity += f", exec_id={exec_id}"
+        super().__init__(f"exec {phase} requires recovery ({identity})")
+
+
+def classify_error(exc: BaseException) -> str:
+    """把 SDK 异常映射为稳定分类字符串，供上层 Adapter 转换为通用契约错误码。
+
+    返回值（枚举式字符串，取值长期稳定）：
+
+    - ``"invalid_request"``：请求本身不合法，不可重试。
+      APIError 4xx（401/403/404/409/412/429 除外）；本地参数校验 ValueError。
+    - ``"unauthorized"``：APIError 401/403。
+    - ``"not_found"``：APIError 404。
+    - ``"conflict"``：APIError 409/412（含 operation/版本冲突）。
+    - ``"rate_limited"``：APIError 429。
+    - ``"transient"``：APIError 5xx；可按 retry_advice 有限重试观察类请求。
+    - ``"transport"``：TransportError（网络/连接层失败，未获得有效 API 响应）。
+    - ``"protocol"``：ProtocolError、JSON 解析失败（json.JSONDecodeError /
+      UnicodeDecodeError），以及 APIError 3xx（重定向被拒绝，属意外响应）。
+    - ``"unknown"``：其余未归类异常（含无 cause 的 ExecRecoveryError）。
+
+    ExecRecoveryError 代表“结果未知、需按 operation_id 核对”，不是可直接映射的
+    终态错误；此处按其 cause 递归分类，无 cause 时返回 "unknown"。
+    """
+    if isinstance(exc, APIError):
+        status = exc.status_code
+        if status in (401, 403):
+            return "unauthorized"
+        if status == 404:
+            return "not_found"
+        if status in (409, 412):
+            return "conflict"
+        if status == 429:
+            return "rate_limited"
+        if 400 <= status < 500:
+            return "invalid_request"
+        if 500 <= status < 600:
+            return "transient"
+        return "protocol"
+    if isinstance(exc, ExecRecoveryError):
+        return classify_error(exc.cause) if exc.cause is not None else "unknown"
+    if isinstance(exc, ProtocolError):
+        return "protocol"
+    if isinstance(exc, TransportError):
+        return "transport"
+    if isinstance(exc, (json.JSONDecodeError, UnicodeDecodeError)):
+        return "protocol"
+    if isinstance(exc, ValueError):
+        return "invalid_request"
+    return "unknown"

genesis_sandbox_client/execution_governance.py

@@ -0,0 +1,270 @@
+"""原调用治理身份与维护只读证明；不从文件名或 UID 区间推导授权。"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+from .errors import ProtocolError
+
+_DIGEST = re.compile(r"[0-9a-f]{64}\Z")
+_CONTEXT = {
+    "tenant_id",
+    "user_id",
+    "run_id",
+    "trace_id",
+    "authorization_scope",
+    "decision_reference",
+    "subject_kind",
+    "invocation_id",
+    "execution_id",
+    "attempt_id",
+}
+
+
+def _object(value: Any, fields: set[str], name: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != fields:
+        raise ValueError(f"{name} requires exact original fields")
+    return value
+
+
+def _opaque(value: Any, name: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value.encode("utf-8")) > 256
+        or any(ord(char) < 32 or ord(char) == 127 or char in "\u2028\u2029" for char in value)
+    ):
+        raise ValueError(f"{name} requires a bounded opaque identity")
+    return value
+
+
+def call_context(value: Any) -> dict[str, Any]:
+    context = _object(value, _CONTEXT, "context")
+    for key in ("tenant_id", "user_id", "run_id", "trace_id", "authorization_scope"):
+        _opaque(context[key], key)
+    if context["subject_kind"] != "enterprise":
+        raise ValueError("enterprise call context required")
+    if context["decision_reference"] is not None:
+        _opaque(context["decision_reference"], "decision_reference")
+    if any(context[key] is not None for key in ("invocation_id", "execution_id", "attempt_id")):
+        for key in ("invocation_id", "execution_id", "attempt_id"):
+            _opaque(context[key], key)
+    return copy.deepcopy(context)
+
+
+def lease_ref(value: Any) -> dict[str, Any]:
+    lease = _object(value, {"provider_id", "lease_id", "workspace", "generation", "expires_at"}, "lease_ref")
+    workspace = _object(
+        lease["workspace"], {"workspace_key", "provider_id", "resource_id", "scope", "generation"}, "workspace_ref"
+    )
+    for obj, keys in (
+        (lease, ("provider_id", "lease_id")),
+        (workspace, ("workspace_key", "provider_id", "resource_id", "scope")),
+    ):
+        for key in keys:
+            _opaque(obj[key], key)
+        if type(obj["generation"]) is not int or not 0 < obj["generation"] <= 2**63 - 1:
+            raise ValueError("original reference generation must be a positive int64")
+    if lease["provider_id"] != workspace["provider_id"]:
+        raise ValueError("original lease/workspace provider mismatch")
+    if not isinstance(lease["expires_at"], str):
+        raise ValueError("original lease timestamp required")
+    timestamp = datetime.fromisoformat(lease["expires_at"].replace("Z", "+00:00"))
+    if timestamp.tzinfo is None or timestamp.utcoffset() != UTC.utcoffset(timestamp):
+        raise ValueError("original lease timestamp must be UTC")
+    return copy.deepcopy(lease)
+
+
+def trusted_governance(value: Any) -> dict[str, Any]:
+    record = _object(
+        value,
+        {
+            "context",
+            "lease_ref",
+            "platform_operation_id",
+            "request_digest",
+            "source_identity",
+            "workspace_id",
+            "authorized_work_write",
+        },
+        "trusted_governance",
+    )
+    call_context(record["context"])
+    if any(record["context"][key] is None for key in ("invocation_id", "execution_id", "attempt_id")):
+        raise ValueError("governed execution requires complete original invocation identity")
+    lease_ref(record["lease_ref"])
+    if record["lease_ref"]["workspace"]["scope"] != record["context"]["authorization_scope"]:
+        raise ValueError("original lease scope differs from trusted execution context")
+    for key in ("platform_operation_id", "workspace_id"):
+        _opaque(record[key], key)
+    for key in ("request_digest", "source_identity"):
+        if not isinstance(record[key], str) or not _DIGEST.fullmatch(record[key]):
+            raise ValueError(f"{key} must be a lowercase SHA256")
+    if type(record["authorized_work_write"]) is not bool:
+        raise ValueError("work-write authorization must be a trusted boolean")
+    if not record["authorized_work_write"]:
+        raise ValueError("per-invocation read-only work enforcement is unavailable")
+    return copy.deepcopy(record)
+
+
+def maintenance_query(
+    workspace_id: str, context: dict[str, Any], operation_id: str, source_identity: str, claim_digest: str
+) -> dict[str, Any]:
+    payload = {
+        "workspace_id": _opaque(workspace_id, "workspace_id"),
+        "context": call_context(context),
+        "operation_id": _opaque(operation_id, "operation_id"),
+        "source_identity": source_identity,
+    }
+    if not isinstance(source_identity, str) or not _DIGEST.fullmatch(source_identity):
+        raise ValueError("source_identity must be a lowercase SHA256")
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    if claim_digest != hashlib.sha256(raw).hexdigest():
+        raise ValueError("original maintenance query digest mismatch")
+    return {**payload, "claim_digest": claim_digest}
+
+
+def maintenance_proof(value: Any, query: dict[str, Any]) -> dict[str, Any]:
+    try:
+        proof = _object(
+            value,
+            {
+                "context",
+                "operation_id",
+                "claim_digest",
+                "source_identity",
+                "root_device",
+                "root_inode",
+                "calls",
+                "leaves",
+            },
+            "maintenance_proof",
+        )
+        for key in ("context", "operation_id", "claim_digest", "source_identity"):
+            if proof[key] != query[key]:
+                raise ValueError("original maintenance query scope changed")
+        for key in ("root_device", "root_inode"):
+            if type(proof[key]) is not int or not 0 <= proof[key] <= 2**63 - 1:
+                raise ValueError("source root tuple exceeds signed int64")
+        if proof["root_inode"] == 0 or not isinstance(proof["calls"], list) or len(proof["calls"]) > 10000:
+            raise ValueError("original same-source call list exceeds bound")
+        calls: dict[str, dict[str, Any]] = {}
+        seen_uids: set[int] = set()
+        for call in proof["calls"]:
+            _object(
+                call,
+                {
+                    "call_id",
+                    "context",
+                    "lease_ref",
+                    "operation_id",
+                    "request_digest",
+                    "execution_id",
+                    "output_directory",
+                    "uid",
+                    "gid",
+                    "root_device",
+                    "root_inode",
+                    "authorized_work_write",
+                    "stop_confirmed",
+                },
+                "maintenance_call",
+            )
+            call_context(call["context"])
+            if (
+                any(call["context"][key] is None for key in ("invocation_id", "execution_id", "attempt_id"))
+                or call["execution_id"] != call["context"]["execution_id"]
+            ):
+                raise ValueError("original call execution identity mismatch")
+            lease_ref(call["lease_ref"])
+            if call["lease_ref"]["workspace"]["scope"] != call["context"]["authorization_scope"]:
+                raise ValueError("original call lease scope differs from context")
+            for key in ("call_id", "operation_id", "execution_id"):
+                _opaque(call[key], key)
+            if (
+                call["context"]["tenant_id"] != query["context"]["tenant_id"]
+                or call["context"]["user_id"] != query["context"]["user_id"]
+            ):
+                raise ValueError("foreign same-source call owner")
+            if call["stop_confirmed"] is not True or type(call["authorized_work_write"]) is not bool:
+                raise ValueError("original stop/work-write facts missing")
+            if not isinstance(call["request_digest"], str) or not _DIGEST.fullmatch(call["request_digest"]):
+                raise ValueError("original request digest missing")
+            for key in ("uid", "gid", "root_inode", "root_device"):
+                if type(call[key]) is not int or not 0 <= call[key] <= 2**63 - 1:
+                    raise ValueError("original allocation tuple exceeds signed int64")
+            if min(call["uid"], call["gid"], call["root_inode"]) < 1 or call["root_device"] != proof["root_device"]:
+                raise ValueError("original same-source allocation mismatch")
+            if call["call_id"] in calls or call["uid"] in seen_uids:
+                raise ValueError("ambiguous original allocation identity")
+            if not isinstance(call["output_directory"], str) or not re.fullmatch(
+                r"output/[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", call["output_directory"]
+            ):
+                raise ValueError("original output root is not a single managed segment")
+            calls[call["call_id"]] = call
+            seen_uids.add(call["uid"])
+        if not isinstance(proof["leaves"], list) or len(proof["leaves"]) > 100000:
+            raise ValueError("maintenance leaf budget exceeded")
+        seen_paths: set[str] = set()
+        for leaf in proof["leaves"]:
+            _object(leaf, {"path", "device", "inode", "uid", "gid", "mode", "directory", "call_id"}, "maintenance_leaf")
+            path = leaf["path"]
+            if (
+                not isinstance(path, str)
+                or path.split("/")[0] not in {"work", "output"}
+                or any(part in {"", ".", ".."} for part in path.split("/"))
+                or path in seen_paths
+            ):
+                raise ValueError("maintenance leaf path invalid or duplicate")
+            seen_paths.add(path)
+            for key in ("device", "inode", "uid", "gid", "mode"):
+                if type(leaf[key]) is not int or not 0 <= leaf[key] <= 2**63 - 1:
+                    raise ValueError("maintenance leaf tuple invalid")
+            if (
+                leaf["inode"] < 1
+                or leaf["device"] != proof["root_device"]
+                or leaf["mode"] > 0o7777
+                or type(leaf["directory"]) is not bool
+            ):
+                raise ValueError("maintenance leaf source/type/mode invalid")
+            if leaf["call_id"] is not None and leaf["call_id"] not in calls:
+                raise ValueError("maintenance leaf references an unknown original call")
+            if leaf["call_id"] is not None:
+                owner = calls[leaf["call_id"]]
+                if path == owner["output_directory"]:
+                    if (
+                        not leaf["directory"]
+                        or leaf["uid"] != 0
+                        or leaf["gid"] != owner["gid"]
+                        or leaf["device"] != owner["root_device"]
+                        or leaf["inode"] != owner["root_inode"]
+                        or leaf["mode"] != 0o770
+                    ):
+                        raise ValueError("original managed output root changed")
+                elif (
+                    leaf["uid"] != owner["uid"]
+                    or leaf["gid"] not in {owner["gid"], 65532}
+                    or (path.startswith("work/") and not owner["authorized_work_write"])
+                    or (path.startswith("output/") and not path.startswith(owner["output_directory"] + "/"))
+                ):
+                    raise ValueError("maintenance leaf original call ownership mismatch")
+            elif leaf["uid"] not in {0, 65532} or (
+                path.startswith("output/") and leaf["uid"] == 0 and leaf["gid"] >= 100001
+            ):
+                raise ValueError("foreign leaf original call identity absent")
+        if not {"work", "output"} <= seen_paths:
+            raise ValueError("maintenance public root tuples absent")
+        for call in calls.values():
+            if not any(
+                leaf["path"] == call["output_directory"] and leaf["call_id"] == call["call_id"]
+                for leaf in proof["leaves"]
+            ):
+                raise ValueError("original call output root proof absent")
+        return copy.deepcopy(proof)
+    except (ValueError, TypeError, KeyError) as exc:
+        raise ProtocolError(str(exc)) from exc

genesis_sandbox_client/invocation_output.py

@@ -0,0 +1,11 @@
+"""调用输出协议只携带逻辑单段目录，不接受宿主路径授权。"""
+
+import re
+
+
+def output_request(value: str | None) -> dict[str, str]:
+    if value is None:
+        return {}
+    if not isinstance(value, str) or not re.fullmatch(r"output/[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", value):
+        raise ValueError("invalid invocation output directory")
+    return {"output_directory": value}

genesis_sandbox_client/json_codec.py

@@ -0,0 +1,31 @@
+"""响应JSON拒绝重复字段和非有限数值，避免原调用身份被最后字段覆盖。"""
+
+import json
+import math
+from typing import Any
+
+from .errors import ProtocolError
+
+
+def _object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ProtocolError("sandbox response contains duplicate JSON fields")
+        result[key] = value
+    return result
+
+
+def _nonfinite(value: str) -> None:
+    raise ProtocolError("sandbox response contains non-finite JSON number")
+
+
+def _float(value: str) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ProtocolError("sandbox response contains overflowing JSON number")
+    return number
+
+
+def loads(value: str | bytes) -> Any:
+    return json.loads(value, object_pairs_hook=_object, parse_constant=_nonfinite, parse_float=_float)