opensandbox-code-interpreter 0.1.2.dev0__tar.gz → 1.1.0__tar.gz

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/.gitignore

@@ -133,6 +133,8 @@ dist
 # Gatsby files
 .cache/
 public
+!docs/public/
+!docs/public/CNAME
 
 # Serverless directories
 .serverless/
@@ -222,6 +224,9 @@ secrets/
 
 # Generated API documentation
 docs/generated/
+docs/.vitepress/generated/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 apidocs/
 
 # Test results
@@ -263,3 +268,29 @@ nbdist/
 # Generated files
 generated/
 **/generated/**
+
+# Fast Sandbox FastPath gRPC stubs are committed intentionally (deterministic protoc
+# output; the server package needs them at install time, so they are checked
+# in rather than regenerated).
+!server/opensandbox_server/services/fast_sandbox/generated/
+!server/opensandbox_server/services/fast_sandbox/generated/**
+server/opensandbox_server/services/fast_sandbox/generated/__pycache__/
+
+# execd eBPF kernel BTF dumps (bpf2go build-time only, never committed —
+# see components/execd/pkg/ebpf/prog/audit.bpf.c; regenerate with:
+#   bpftool btf dump file /sys/kernel/btf/vmlinux format c > .../vmlinux.h)
+components/execd/pkg/ebpf/prog/vmlinux.h
+components/execd/pkg/ebpf/prog/vmlinux_*.h
+
+# gVisor runtime binaries (downloaded dynamically)
+kubernetes/test/kind/gvisor/runsc
+kubernetes/test/kind/gvisor/containerd-shim-runsc-v1
+bin/
+obj/
+
+.qoder/
+/.vs
+
+# fast-sandbox pinned source checkout (materialized by
+# manifests/release/build-fast-sandbox.sh from manifests/third-party/fast-sandbox.commit)
+.fast-sandbox/

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: opensandbox-code-interpreter
-Version: 0.1.2.dev0
+Version: 1.1.0
 Summary: OpenSandbox Code Interpreter Python SDK - Advanced code execution with persistent contexts
-Project-URL: Homepage, https://github.com/alibaba/OpenSandbox
-Project-URL: Repository, https://github.com/alibaba/OpenSandbox
-Project-URL: Documentation, https://docs.opensandbox.io
-Project-URL: Issues, https://github.com/alibaba/OpenSandbox/issues
+Project-URL: Homepage, https://open-sandbox.ai
+Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
+Project-URL: Documentation, https://open-sandbox.ai
+Project-URL: Issues, https://github.com/opensandbox-group/OpenSandbox/issues
 Author-email: OpenSandbox Team <ninan.nn@alibaba-inc.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -223,13 +223,12 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: opensandbox<0.2.0,>=0.1.1
-Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: opensandbox<2.0.0,>=1.1.0
+Requires-Dist: pydantic<3.0,>=2.4.2
 Description-Content-Type: text/markdown
 
 # OpenSandbox Code Interpreter SDK for Python
 
-English | [中文](README_zh.md)
 
 A Python SDK for executing code in secure, isolated sandboxes. It provides a high-level API for running Python, Java,
 Go, TypeScript, and other languages safely, with support for code execution contexts.
@@ -241,7 +240,7 @@ This SDK requires a Docker image containing the Code Interpreter runtime environ
 Node.js, etc.
 
 For detailed information about supported languages and versions, refer to the
-[Environment Documentation](../../../sandboxes/code-interpreter/README.md).
+[Environment Documentation](https://github.com/opensandbox-group/sandbox-images).
 
 ## Installation
 
@@ -281,9 +280,9 @@ async def main() -> None:
 
     # 2. Create a Sandbox with the code-interpreter image + runtime versions
     sandbox = await Sandbox.create(
-        "opensandbox/code-interpreter:latest",
+        "opensandbox/code-interpreter:v1.1.0",
         connection_config=config,
-        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
+        entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
         env={
             "PYTHON_VERSION": "3.11",
             "JAVA_VERSION": "17",
@@ -342,9 +341,9 @@ config = ConnectionConfigSync(
 )
 
 sandbox = SandboxSync.create(
-    "opensandbox/code-interpreter:latest",
+    "opensandbox/code-interpreter:v1.1.0",
     connection_config=config,
-    entrypoint=["/opt/opensandbox/code-interpreter.sh"],
+    entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
     env={"PYTHON_VERSION": "3.11"},
 )
 with sandbox:
@@ -355,6 +354,14 @@ with sandbox:
     sandbox.kill()
 ```
 
+### Installing Python packages at runtime
+
+You can install packages directly via `sandbox.commands.run(...)`:
+
+```python
+execution = await sandbox.commands.run("pip install pandas numpy")
+```
+
 ## Runtime Configuration
 
 ### Docker Image

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/README.md

@@ -1,6 +1,5 @@
 # OpenSandbox Code Interpreter SDK for Python
 
-English | [中文](README_zh.md)
 
 A Python SDK for executing code in secure, isolated sandboxes. It provides a high-level API for running Python, Java,
 Go, TypeScript, and other languages safely, with support for code execution contexts.
@@ -12,7 +11,7 @@ This SDK requires a Docker image containing the Code Interpreter runtime environ
 Node.js, etc.
 
 For detailed information about supported languages and versions, refer to the
-[Environment Documentation](../../../sandboxes/code-interpreter/README.md).
+[Environment Documentation](https://github.com/opensandbox-group/sandbox-images).
 
 ## Installation
 
@@ -52,9 +51,9 @@ async def main() -> None:
 
     # 2. Create a Sandbox with the code-interpreter image + runtime versions
     sandbox = await Sandbox.create(
-        "opensandbox/code-interpreter:latest",
+        "opensandbox/code-interpreter:v1.1.0",
         connection_config=config,
-        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
+        entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
         env={
             "PYTHON_VERSION": "3.11",
             "JAVA_VERSION": "17",
@@ -113,9 +112,9 @@ config = ConnectionConfigSync(
 )
 
 sandbox = SandboxSync.create(
-    "opensandbox/code-interpreter:latest",
+    "opensandbox/code-interpreter:v1.1.0",
     connection_config=config,
-    entrypoint=["/opt/opensandbox/code-interpreter.sh"],
+    entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
     env={"PYTHON_VERSION": "3.11"},
 )
 with sandbox:
@@ -126,6 +125,14 @@ with sandbox:
     sandbox.kill()
 ```
 
+### Installing Python packages at runtime
+
+You can install packages directly via `sandbox.commands.run(...)`:
+
+```python
+execution = await sandbox.commands.run("pip install pandas numpy")
+```
+
 ## Runtime Configuration
 
 ### Docker Image

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/pyproject.toml

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -42,15 +42,15 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "pydantic>=2.0.0,<3.0",
-    "opensandbox>=0.1.1,<0.2.0",
+    "pydantic>=2.4.2,<3.0",
+    "opensandbox>=1.1.0,<2.0.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/alibaba/OpenSandbox"
-Repository = "https://github.com/alibaba/OpenSandbox"
-Documentation = "https://docs.opensandbox.io"
-Issues = "https://github.com/alibaba/OpenSandbox/issues"
+Homepage = "https://open-sandbox.ai"
+Repository = "https://github.com/opensandbox-group/OpenSandbox"
+Documentation = "https://open-sandbox.ai"
+Issues = "https://github.com/opensandbox-group/OpenSandbox/issues"
 
 [tool.hatch.version]
 source = "vcs"
@@ -58,9 +58,9 @@ source = "vcs"
 [tool.hatch.version.raw-options]
 # This package is in a subdirectory; explicitly point setuptools-scm at the git root.
 root = "../../.."
-tag_regex = "^python/code-interpreter/v(?P<version>\\d+\\.\\d+\\.\\d+(?:[\\.\\w\\+\\-]*)?)$"
-git_describe_command = 'git describe --dirty --tags --long --match "python/code-interpreter/v*"'
-fallback_version = "0.1.0"
+tag_regex = "^release-(?P<version>\\d+\\.\\d+\\.\\d+(?:[\\.\\w\\+\\-]*)?)$"
+git_describe_command = 'git describe --dirty --tags --long --match "release-*"'
+fallback_version = "0.1.3"
 
 [tool.hatch.build]
 include = [

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/adapters/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/adapters/code_adapter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,6 +22,7 @@ API clients and handling SSE streaming for real-time code execution.
 
 import json
 import logging
+import time
 
 import httpx
 from opensandbox.adapters.converter.event_node import EventNode
@@ -32,6 +33,7 @@ from opensandbox.adapters.converter.execution_event_dispatcher import (
     ExecutionEventDispatcher,
 )
 from opensandbox.adapters.converter.response_handler import (
+    extract_request_id,
     handle_api_error,
     require_parsed,
 )
@@ -39,6 +41,7 @@ from opensandbox.config import ConnectionConfig
 from opensandbox.exceptions import InvalidArgumentException, SandboxApiException
 from opensandbox.models.execd import Execution, ExecutionHandlers
 from opensandbox.models.sandboxes import SandboxEndpoint
+from opensandbox.transport import unwrap_retry_transport
 
 from code_interpreter.adapters.converter.code_execution_converter import (
     CodeExecutionConverter,
@@ -49,6 +52,22 @@ from code_interpreter.services.code import Codes
 logger = logging.getLogger(__name__)
 
 
+def _normalize_sse_event(event_dict: dict) -> dict:
+    if "type" in event_dict and "timestamp" in event_dict:
+        return event_dict
+    if "code" in event_dict and "message" in event_dict:
+        return {
+            "type": "error",
+            "timestamp": int(time.time() * 1000),
+            "error": {
+                "ename": str(event_dict["code"]),
+                "evalue": str(event_dict["message"]),
+                "traceback": [],
+            },
+        }
+    return event_dict
+
+
 class CodesAdapter(Codes):
     """
     Adapter implementation for code execution service.
@@ -88,6 +107,7 @@ class CodesAdapter(Codes):
         headers = {
             "User-Agent": self.connection_config.user_agent,
             **self.connection_config.headers,
+            **self.execd_endpoint.headers,
         }
 
         # Execd API does not require authentication
@@ -111,6 +131,9 @@ class CodesAdapter(Codes):
             "Accept": "text/event-stream",
             "Cache-Control": "no-cache",
         }
+        # SSE bootstraps bypass the retry wrapper: request bodies are
+        # not replayable and a non-idempotent status opt-in would cause
+        # duplicate execution on a resent SSE POST.
         self._sse_client = httpx.AsyncClient(
             headers=sse_headers,
             timeout=httpx.Timeout(
@@ -119,7 +142,7 @@ class CodesAdapter(Codes):
                 write=timeout_seconds,
                 pool=None,
             ),
-            transport=self.connection_config.transport,
+            transport=unwrap_retry_transport(self.connection_config.transport),
         )
 
     async def _get_client(self):
@@ -197,7 +220,9 @@ class CodesAdapter(Codes):
             )
             handle_api_error(response_obj, "List code contexts")
             parsed_list = require_parsed(response_obj, list, "List code contexts")
-            return [CodeExecutionConverter.from_api_code_context(c) for c in parsed_list]
+            return [
+                CodeExecutionConverter.from_api_code_context(c) for c in parsed_list
+            ]
         except Exception as e:
             logger.error("Failed to list contexts", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
@@ -250,7 +275,11 @@ class CodesAdapter(Codes):
             raise InvalidArgumentException("Code cannot be empty")
 
         try:
-            if context is not None and language is not None and context.language != language:
+            if (
+                context is not None
+                and language is not None
+                and context.language != language
+            ):
                 raise InvalidArgumentException(
                     f"language '{language}' must match context.language '{context.language}'"
                 )
@@ -280,13 +309,12 @@ class CodesAdapter(Codes):
                     await response.aread()
                     error_body = response.text
                     logger.error(
-                        "Failed to run code. Status: %s, Body: %s",
-                        response.status_code,
-                        error_body,
+                        f"Failed to run code. Status: {response.status_code}, Body: {error_body}"
                     )
                     raise SandboxApiException(
-                        message=f"Failed to run code. Status code: {response.status_code}",
+                        message=f"Failed to run code. Status code: {response.status_code}, Body: {error_body}",
                         status_code=response.status_code,
+                        request_id=extract_request_id(response.headers),
                     )
 
                 dispatcher = ExecutionEventDispatcher(execution, handlers)
@@ -301,22 +329,20 @@ class CodesAdapter(Codes):
                         data = data[5:].strip()
 
                     try:
-                        event_dict = json.loads(data)
+                        event_dict = _normalize_sse_event(json.loads(data))
                         event_node = EventNode(**event_dict)
                         await dispatcher.dispatch(event_node)
                     except json.JSONDecodeError:
-                        logger.debug("Failed to parse SSE line: %s", line)
+                        logger.debug(f"Failed to parse SSE line: {line}")
                         continue
                     except Exception as e:
-                        logger.error("Error processing event: %s", data, exc_info=e)
+                        logger.error(f"Error processing event: {data}", exc_info=e)
                         continue
 
             return execution
 
         except Exception as e:
-            logger.error(
-                "Failed to run code (length: %s)", len(code), exc_info=e
-            )
+            logger.error(f"Failed to run code (length: {len(code)})", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
 
     async def interrupt(self, execution_id: str) -> None:
@@ -339,3 +365,23 @@ class CodesAdapter(Codes):
         except Exception as e:
             logger.error("Failed to interrupt code execution", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    async def ping(self) -> bool:
+        """
+        Check if the execd code execution service is alive.
+
+        Uses the shared generated API client so the ping exercises the same
+        HTTP client and endpoint that serve code execution requests.
+        """
+        try:
+            from opensandbox.api.execd.api.health import ping as ping_api
+
+            client = await self._get_client()
+            response_obj = await ping_api.asyncio_detailed(client=client)
+
+            handle_api_error(response_obj, "Ping code interpreter")
+            return True
+
+        except Exception as e:
+            logger.debug(f"Code interpreter ping failed: {e}")
+            return False

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/adapters/converter/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/adapters/converter/code_execution_converter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/adapters/factory.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/code_interpreter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,12 +21,16 @@ functionality with specialized code execution features, including multi-language
 support, session management, and variable persistence.
 """
 
+import asyncio
 import logging
+import time
+from datetime import timedelta
 
 from opensandbox.exceptions import (
     InvalidArgumentException,
     SandboxException,
     SandboxInternalException,
+    SandboxReadyTimeoutException,
 )
 from opensandbox.sandbox import Sandbox
 
@@ -35,6 +39,21 @@ from code_interpreter.services.code import Codes
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_READY_TIMEOUT = timedelta(seconds=30)
+DEFAULT_HEALTH_CHECK_POLLING_INTERVAL = timedelta(milliseconds=200)
+
+# Strict health check script: verifies the code interpreter runtime (Jupyter
+# kernel gateway) is actually serving inside the sandbox. execd starts serving
+# /ping before the entrypoint launches Jupyter, and the setup stage may run
+# short-lived "jupyter kernelspec" helpers, so a daemon ping or a process-name
+# grep cannot prove the runtime is ready. Probing the Jupyter listen port
+# (127.0.0.1:${JUPYTER_PORT:-44771}, same default as the entrypoint) only
+# passes once the server accepts connections.
+RUNTIME_PROCESS_CHECK_COMMAND = (
+    "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${JUPYTER_PORT:-44771}' "
+    "&& exit 0 || exit 1"
+)
+
 
 class CodeInterpreter:
     """
@@ -169,14 +188,114 @@ class CodeInterpreter:
         """
         return self._code_service
 
+    async def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise
+        """
+        return await self._code_service.ping()
+
+    async def is_healthy(self) -> bool:
+        """
+        Check if the code interpreter is healthy (strict check).
+
+        Healthy means both:
+
+        - the code execution service (execd) answers ``GET /ping``; and
+        - the code interpreter runtime (Jupyter kernel gateway) is serving
+          inside the sandbox, verified by probing its listen port through the
+          execd command API.
+
+        Exceptions raised by either leg are treated as unhealthy.
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        try:
+            return await self.ping() and await self._is_runtime_process_alive()
+        except Exception:
+            return False
+
+    async def _is_runtime_process_alive(self) -> bool:
+        """
+        Check if the code interpreter runtime (Jupyter) is serving.
+
+        Probes the runtime listen port through the sandbox command service and
+        treats a failed command (non-zero exit surfaced as an execution error)
+        as an unhealthy runtime.
+        """
+        try:
+            execution = await self._sandbox.commands.run(
+                RUNTIME_PROCESS_CHECK_COMMAND
+            )
+            return execution.error is None
+        except Exception:
+            return False
+
+    async def check_ready(
+        self,
+        timeout: timedelta,
+        polling_interval: timedelta,
+    ) -> None:
+        """
+        Wait for the code interpreter to pass the strict health check with polling.
+
+        Raises:
+            SandboxReadyTimeoutException: if the health check doesn't pass within timeout
+        """
+        logger.info(
+            f"Waiting for code interpreter {self.id} to pass health check "
+            f"(timeout: {timeout.total_seconds()}s)"
+        )
+
+        deadline = time.monotonic() + timeout.total_seconds()
+        attempt = 0
+
+        while time.monotonic() < deadline:
+            attempt += 1
+            if await self.is_healthy():
+                logger.info(
+                    f"Code interpreter {self.id} passed health check "
+                    f"after {attempt} attempts"
+                )
+                return
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            await asyncio.sleep(min(polling_interval.total_seconds(), remaining))
+
+        raise SandboxReadyTimeoutException(
+            f"Code interpreter {self.id} health check timed out after "
+            f"{timeout.total_seconds()}s ({attempt} attempts). The code execution "
+            f"service (execd) or the interpreter runtime (Jupyter) did not become "
+            f"ready. Pass skip_health_check=True to skip this check."
+        )
+
     @classmethod
-    async def create(cls, sandbox: Sandbox) -> "CodeInterpreter":
+    async def create(
+        cls,
+        sandbox: Sandbox,
+        *,
+        ready_timeout: timedelta = DEFAULT_READY_TIMEOUT,
+        health_check_polling_interval: timedelta = DEFAULT_HEALTH_CHECK_POLLING_INTERVAL,
+        skip_health_check: bool = False,
+    ) -> "CodeInterpreter":
         """
         Creates a CodeInterpreter from an existing Sandbox instance.
 
         This factory method handles the creation and initialization of CodeInterpreter
         services, including the code execution service and language configuration.
 
+        By default a strict health check runs before the interpreter is returned:
+        the code execution service (execd) must answer ``GET /ping`` AND the
+        code interpreter runtime (Jupyter kernel gateway) must be serving,
+        both within ``ready_timeout``. execd starts serving before the runtime
+        launches, so the daemon ping alone is not enough. Set
+        ``skip_health_check=True`` to opt out.
+
         CodeInterpreter must be created by wrapping an existing Sandbox instance with
         code execution capabilities. This design ensures clear separation of concerns:
         - Sandbox handles infrastructure (containers, resources, networking)
@@ -184,6 +303,10 @@ class CodeInterpreter:
 
         Args:
             sandbox: Existing sandbox instance to wrap with code execution capabilities
+            ready_timeout: Maximum time to wait for the code execution service health check
+            health_check_polling_interval: Time between health check attempts
+            skip_health_check: If True, do not wait for the code execution service
+                to become ready; the returned interpreter may fail on first use
 
         Returns:
             CodeInterpreter instance wrapping the sandbox
@@ -191,24 +314,34 @@ class CodeInterpreter:
         Raises:
             InvalidArgumentException: If sandbox is not provided
             SandboxException: If creation fails
+            SandboxReadyTimeoutException: If the code execution service health check
+                times out and ``skip_health_check`` is False
             SandboxInternalException: If internal service initialization fails
         """
         if sandbox is None:
             raise InvalidArgumentException("Sandbox instance must be provided")
 
-        logger.info("Creating code interpreter from sandbox: %s", sandbox.id)
+        logger.info(f"Creating code interpreter from sandbox: {sandbox.id}")
 
         factory = AdapterFactory(sandbox.connection_config)
 
         try:
             # Connect to the execd daemon endpoint for code execution services
             from opensandbox.constants import DEFAULT_EXECD_PORT
+
             code_interpreter_endpoint = await sandbox.get_endpoint(DEFAULT_EXECD_PORT)
-            code_execution_service = factory.create_code_execution_service(code_interpreter_endpoint)
+            code_execution_service = factory.create_code_execution_service(
+                code_interpreter_endpoint
+            )
+
+            interpreter = cls(sandbox, code_execution_service)
+
+            if not skip_health_check:
+                await interpreter.check_ready(ready_timeout, health_check_polling_interval)
 
-            logger.info("Code interpreter %s created successfully", sandbox.id)
+            logger.info(f"Code interpreter {sandbox.id} created successfully")
 
-            return cls(sandbox, code_execution_service)
+            return interpreter
         except Exception as e:
             if isinstance(e, SandboxException):
                 raise

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/models/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/models/code.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/models/code_sync.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/services/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/services/code.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -212,3 +212,17 @@ class Codes(Protocol):
             SandboxException: If interruption fails
         """
         ...
+
+    async def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is alive.
+
+        The ping targets the execd daemon endpoint used by this service
+        (``GET /ping``). It does not verify that a specific language runtime
+        is ready, only that the daemon serving code execution requests is
+        responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise
+        """
+        ...

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/adapters/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/adapters/code_adapter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@ Synchronous adapter for code execution service (including SSE streaming).
 
 import json
 import logging
+import time
 
 import httpx
 from opensandbox.adapters.converter.event_node import EventNode
@@ -26,6 +27,7 @@ from opensandbox.adapters.converter.exception_converter import (
     ExceptionConverter,
 )
 from opensandbox.adapters.converter.response_handler import (
+    extract_request_id,
     handle_api_error,
     require_parsed,
 )
@@ -37,6 +39,7 @@ from opensandbox.models.sandboxes import SandboxEndpoint
 from opensandbox.sync.adapters.converter.execution_event_dispatcher import (
     ExecutionEventDispatcherSync,
 )
+from opensandbox.transport import unwrap_retry_transport
 
 from code_interpreter.models.code_sync import CodeContextSync, SupportedLanguageSync
 from code_interpreter.sync.services.code import CodesSync
@@ -44,6 +47,22 @@ from code_interpreter.sync.services.code import CodesSync
 logger = logging.getLogger(__name__)
 
 
+def _normalize_sse_event(event_dict: dict) -> dict:
+    if "type" in event_dict and "timestamp" in event_dict:
+        return event_dict
+    if "code" in event_dict and "message" in event_dict:
+        return {
+            "type": "error",
+            "timestamp": int(time.time() * 1000),
+            "error": {
+                "ename": str(event_dict["code"]),
+                "evalue": str(event_dict["message"]),
+                "traceback": [],
+            },
+        }
+    return event_dict
+
+
 class CodesAdapterSync(CodesSync):
     """
     Synchronous adapter for code execution service.
@@ -63,7 +82,9 @@ class CodesAdapterSync(CodesSync):
     RUN_CODE_PATH = "/code"
     CREATE_CONTEXT_PATH = "/code/context"
 
-    def __init__(self, execd_endpoint: SandboxEndpoint, connection_config: ConnectionConfigSync) -> None:
+    def __init__(
+        self, execd_endpoint: SandboxEndpoint, connection_config: ConnectionConfigSync
+    ) -> None:
         """
         Initialize the code service adapter (sync).
 
@@ -78,7 +99,11 @@ class CodesAdapterSync(CodesSync):
         base_url = f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}"
         timeout_seconds = self.connection_config.request_timeout.total_seconds()
         timeout = httpx.Timeout(timeout_seconds)
-        headers = {"User-Agent": self.connection_config.user_agent, **self.connection_config.headers}
+        headers = {
+            "User-Agent": self.connection_config.user_agent,
+            **self.connection_config.headers,
+            **(self.execd_endpoint.headers or {}),
+        }
 
         self._client = Client(base_url=base_url, timeout=timeout)
         self._httpx_client = httpx.Client(
@@ -89,16 +114,27 @@ class CodesAdapterSync(CodesSync):
         )
         self._client.set_httpx_client(self._httpx_client)
 
-        sse_headers = {**headers, "Accept": "text/event-stream", "Cache-Control": "no-cache"}
+        sse_headers = {
+            **headers,
+            "Accept": "text/event-stream",
+            "Cache-Control": "no-cache",
+        }
+        # SSE bootstraps bypass the retry wrapper: request bodies are
+        # not replayable and a non-idempotent status opt-in would cause
+        # duplicate execution on a resent SSE POST.
         self._sse_client = httpx.Client(
             headers=sse_headers,
-            timeout=httpx.Timeout(connect=timeout_seconds, read=None, write=timeout_seconds, pool=None),
-            transport=self.connection_config.transport,
+            timeout=httpx.Timeout(
+                connect=timeout_seconds, read=None, write=timeout_seconds, pool=None
+            ),
+            transport=unwrap_retry_transport(self.connection_config.transport),
         )
 
     def _get_execd_url(self, path: str) -> str:
         """Build URL for execd endpoint."""
-        return f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
+        return (
+            f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
+        )
 
     def create_context(self, language: str) -> CodeContextSync:
         """
@@ -225,7 +261,11 @@ class CodesAdapterSync(CodesSync):
             raise InvalidArgumentException("Code cannot be empty")
 
         try:
-            if context is not None and language is not None and context.language != language:
+            if (
+                context is not None
+                and language is not None
+                and context.language != language
+            ):
                 raise InvalidArgumentException(
                     f"language '{language}' must match context.language '{context.language}'"
                 )
@@ -233,7 +273,9 @@ class CodesAdapterSync(CodesSync):
             if context is None:
                 # Default context: language default context (server-side behavior).
                 # When context.id is omitted, execd will create/reuse a default session per language.
-                context = CodeContextSync(language=language or SupportedLanguageSync.PYTHON)
+                context = CodeContextSync(
+                    language=language or SupportedLanguageSync.PYTHON
+                )
             api_request = {
                 "code": code,
                 "context": {
@@ -249,9 +291,11 @@ class CodesAdapterSync(CodesSync):
             with self._sse_client.stream("POST", url, json=api_request) as response:
                 if response.status_code != 200:
                     response.read()
+                    error_body = response.text
                     raise SandboxApiException(
-                        message=f"Failed to run code. Status code: {response.status_code}",
+                        message=f"Failed to run code. Status code: {response.status_code}, Body: {error_body}",
                         status_code=response.status_code,
+                        request_id=extract_request_id(response.headers),
                     )
 
                 for line in response.iter_lines():
@@ -261,19 +305,19 @@ class CodesAdapterSync(CodesSync):
                     if data.startswith("data:"):
                         data = data[5:].strip()
                     try:
-                        event_dict = json.loads(data)
+                        event_dict = _normalize_sse_event(json.loads(data))
                         event_node = EventNode(**event_dict)
                         dispatcher.dispatch(event_node)
                     except json.JSONDecodeError:
-                        logger.debug("Failed to parse SSE line: %s", line)
+                        logger.debug(f"Failed to parse SSE line: {line}")
                         continue
                     except Exception as e:
-                        logger.error("Error processing event: %s", data, exc_info=e)
+                        logger.error(f"Error processing event: {data}", exc_info=e)
                         continue
 
             return execution
         except Exception as e:
-            logger.error("Failed to run code (length: %s)", len(code), exc_info=e)
+            logger.error(f"Failed to run code (length: {len(code)})", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
 
     def interrupt(self, execution_id: str) -> None:
@@ -286,8 +330,27 @@ class CodesAdapterSync(CodesSync):
         try:
             from opensandbox.api.execd.api.code_interpreting import interrupt_code
 
-            response_obj = interrupt_code.sync_detailed(client=self._client, id=execution_id)
+            response_obj = interrupt_code.sync_detailed(
+                client=self._client, id=execution_id
+            )
             handle_api_error(response_obj, "Interrupt code execution")
         except Exception as e:
             logger.error("Failed to interrupt code execution", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def ping(self) -> bool:
+        """
+        Check if the execd code execution service is alive (blocking).
+
+        Uses the shared generated API client so the ping exercises the same
+        HTTP client and endpoint that serve code execution requests.
+        """
+        try:
+            from opensandbox.api.execd.api.health import ping as ping_api
+
+            response_obj = ping_api.sync_detailed(client=self._client)
+            handle_api_error(response_obj, "Ping code interpreter")
+            return True
+        except Exception as e:
+            logger.debug(f"Code interpreter ping failed: {e}")
+            return False

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/adapters/factory.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/code_interpreter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,12 +18,15 @@ Synchronous Code Interpreter SDK.
 """
 
 import logging
+import time
+from datetime import timedelta
 
 from opensandbox.constants import DEFAULT_EXECD_PORT
 from opensandbox.exceptions import (
     InvalidArgumentException,
     SandboxException,
     SandboxInternalException,
+    SandboxReadyTimeoutException,
 )
 from opensandbox.sync.sandbox import SandboxSync
 
@@ -32,6 +35,21 @@ from code_interpreter.sync.services.code import CodesSync
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_READY_TIMEOUT = timedelta(seconds=30)
+DEFAULT_HEALTH_CHECK_POLLING_INTERVAL = timedelta(milliseconds=200)
+
+# Strict health check script: verifies the code interpreter runtime (Jupyter
+# kernel gateway) is actually serving inside the sandbox. execd starts serving
+# /ping before the entrypoint launches Jupyter, and the setup stage may run
+# short-lived "jupyter kernelspec" helpers, so a daemon ping or a process-name
+# grep cannot prove the runtime is ready. Probing the Jupyter listen port
+# (127.0.0.1:${JUPYTER_PORT:-44771}, same default as the entrypoint) only
+# passes once the server accepts connections.
+RUNTIME_PROCESS_CHECK_COMMAND = (
+    "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${JUPYTER_PORT:-44771}' "
+    "&& exit 0 || exit 1"
+)
+
 
 class CodeInterpreterSync:
     """
@@ -146,13 +164,110 @@ class CodeInterpreterSync:
         """
         return self._code_service
 
+    def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise
+        """
+        return self._code_service.ping()
+
+    def is_healthy(self) -> bool:
+        """
+        Check if the code interpreter is healthy (strict check).
+
+        Healthy means both:
+
+        - the code execution service (execd) answers ``GET /ping``; and
+        - the code interpreter runtime (Jupyter kernel gateway) is serving
+          inside the sandbox, verified by probing its listen port through the
+          execd command API.
+
+        Exceptions raised by either leg are treated as unhealthy.
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        try:
+            return self.ping() and self._is_runtime_process_alive()
+        except Exception:
+            return False
+
+    def _is_runtime_process_alive(self) -> bool:
+        """
+        Check if the code interpreter runtime (Jupyter) is serving.
+        """
+        try:
+            execution = self._sandbox.commands.run(RUNTIME_PROCESS_CHECK_COMMAND)
+            return execution.error is None
+        except Exception:
+            return False
+
+    def check_ready(
+        self,
+        timeout: timedelta,
+        polling_interval: timedelta,
+    ) -> None:
+        """
+        Wait for the code interpreter to pass the strict health check with polling (blocking).
+
+        Raises:
+            SandboxReadyTimeoutException: if the health check doesn't pass within timeout
+        """
+        logger.info(
+            f"Waiting for code interpreter {self.id} to pass health check "
+            f"(timeout: {timeout.total_seconds()}s)"
+        )
+
+        deadline = time.monotonic() + timeout.total_seconds()
+        attempt = 0
+
+        while time.monotonic() < deadline:
+            attempt += 1
+            if self.is_healthy():
+                logger.info(
+                    f"Code interpreter {self.id} passed health check "
+                    f"after {attempt} attempts"
+                )
+                return
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            time.sleep(min(polling_interval.total_seconds(), remaining))
+
+        raise SandboxReadyTimeoutException(
+            f"Code interpreter {self.id} health check timed out after "
+            f"{timeout.total_seconds()}s ({attempt} attempts). The code execution "
+            f"service (execd) or the interpreter runtime (Jupyter) did not become "
+            f"ready. Pass skip_health_check=True to skip this check."
+        )
+
     @classmethod
-    def create(cls, sandbox: SandboxSync) -> "CodeInterpreterSync":
+    def create(
+        cls,
+        sandbox: SandboxSync,
+        *,
+        ready_timeout: timedelta = DEFAULT_READY_TIMEOUT,
+        health_check_polling_interval: timedelta = DEFAULT_HEALTH_CHECK_POLLING_INTERVAL,
+        skip_health_check: bool = False,
+    ) -> "CodeInterpreterSync":
         """
         Create a CodeInterpreterSync from an existing SandboxSync instance (blocking).
 
+        By default a strict health check runs before the interpreter is returned:
+        the code execution service (execd) must answer ``GET /ping`` AND the
+        code interpreter runtime process (Jupyter kernel gateway) must be
+        running inside the sandbox, both within ``ready_timeout``. Set
+        ``skip_health_check=True`` to opt out.
+
         Args:
             sandbox: Existing sandbox instance to wrap with code execution capabilities
+            ready_timeout: Maximum time to wait for the code execution service health check
+            health_check_polling_interval: Time between health check attempts
+            skip_health_check: If True, do not wait for the code execution service
+                to become ready; the returned interpreter may fail on first use
 
         Returns:
             CodeInterpreterSync instance wrapping the sandbox
@@ -160,19 +275,29 @@ class CodeInterpreterSync:
         Raises:
             InvalidArgumentException: If sandbox is not provided
             SandboxException: If creation fails
+            SandboxReadyTimeoutException: If the code execution service health check
+                times out and ``skip_health_check`` is False
             SandboxInternalException: If internal service initialization fails
         """
         if sandbox is None:
             raise InvalidArgumentException("Sandbox instance must be provided")
 
-        logger.info("Creating code interpreter from sandbox: %s", sandbox.id)
+        logger.info(f"Creating code interpreter from sandbox: {sandbox.id}")
         factory = AdapterFactorySync(sandbox.connection_config)
         try:
             endpoint = sandbox.get_endpoint(DEFAULT_EXECD_PORT)
             code_service = factory.create_code_execution_service(endpoint)
-            logger.info("Code interpreter %s created successfully", sandbox.id)
-            return cls(sandbox, code_service)
+
+            interpreter = cls(sandbox, code_service)
+
+            if not skip_health_check:
+                interpreter.check_ready(ready_timeout, health_check_polling_interval)
+
+            logger.info(f"Code interpreter {sandbox.id} created successfully")
+            return interpreter
         except Exception as e:
             if isinstance(e, SandboxException):
                 raise
-            raise SandboxInternalException(f"Failed to create code interpreter: {e}", cause=e) from e
+            raise SandboxInternalException(
+                f"Failed to create code interpreter: {e}", cause=e
+            ) from e

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/services/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{opensandbox_code_interpreter-0.1.2.dev0 → opensandbox_code_interpreter-1.1.0}/src/code_interpreter/sync/services/code.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -159,3 +159,17 @@ class CodesSync(Protocol):
             SandboxException: If interruption fails.
         """
         ...
+
+    def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is alive (blocking).
+
+        The ping targets the execd daemon endpoint used by this service
+        (``GET /ping``). It does not verify that a specific language runtime
+        is ready, only that the daemon serving code execution requests is
+        responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise.
+        """
+        ...