Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Check terminal toolkit initial environment setting (#3818)

Abishek Newar4d292ab4728d
diff --git a/camel/toolkits/terminal_toolkit/go_runtime.py b/camel/toolkits/terminal_toolkit/go_runtime.py
new file mode 100644
index 000000000..b8e0ed104
--- /dev/null
+++ b/camel/toolkits/terminal_toolkit/go_runtime.py
@@ -0,0 +1,161 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+r"""Go runtime auto-installation utilities.
+
+This module provides functionality to detect, download, and configure
+the Go programming language runtime. If Go is not already available
+on the system, it is downloaded from the official Go website and
+extracted to ``~/.camel/runtimes/go/``.
+"""
+
+import os
+import shutil
+import subprocess
+from typing import Optional
+
+from camel.logger import get_logger
+
+from .runtime_utils import (
+ GO_CHECKSUM_URL_TEMPLATE,
+ GO_DOWNLOAD_URL_TEMPLATE,
+ GO_VERSION,
+ RUNTIMES_DIR,
+ ArchiveType,
+ RuntimeDownloadError,
+ RuntimeExtractionError,
+ RuntimeInstallError,
+ UpdateCallback,
+ download_and_extract_runtime,
+ get_platform_info,
+)
+
+logger = get_logger(__name__)
+
+
+def ensure_go_available(
+ update_callback: UpdateCallback = None,
+) -> Optional[str]:
+ r"""Ensure Go is available, downloading it if necessary.
+
+ Checks if Go is already installed on the system. If not, downloads
+ the official Go binary for the current platform and extracts it to
+ ``~/.camel/runtimes/go/``.
+
+ Args:
+ update_callback (Callable[[str], None], optional): Callback
+ function to receive status updates.
+ (default: :obj:`None`)
+
+ Returns:
+ Optional[str]: The path to the Go ``bin`` directory that
+ should be added to PATH, or ``None`` if Go could not
+ be made available.
+ """
+ # Check if Go is already available on PATH
+ existing_go = shutil.which("go")
+ if existing_go is not None:
+ try:
+ result = subprocess.run(
+ ["go", "version"],
+ check=False,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ if result.returncode == 0:
+ version_info = result.stdout.strip()
+ info = (
+ f"Go is already available: {version_info}"
+ )
+ if update_callback:
+ update_callback(f"{info}\n")
+ return os.path.dirname(existing_go)
+ except Exception:
+ pass
+
+ # Go not found, attempt auto-install
+ if update_callback:
+ update_callback(
+ f"Go not found, installing Go {GO_VERSION}...\n"
+ )
+
+ try:
+ os_name, arch = get_platform_info()
+ except RuntimeError as e:
+ if update_callback:
+ update_callback(
+ f"Cannot auto-install Go: {e}\n"
+ )
+ return None
+
+ # Construct download URL from template
+ ext: ArchiveType = (
+ "zip" if os_name == "windows" else "tar.gz"
+ )
+ url = GO_DOWNLOAD_URL_TEMPLATE.format(
+ version=GO_VERSION, os_name=os_name, arch=arch, ext=ext,
+ )
+ checksum_url = GO_CHECKSUM_URL_TEMPLATE.format(
+ version=GO_VERSION, os_name=os_name, arch=arch, ext=ext,
+ )
+
+ go_runtime_dir = os.path.join(RUNTIMES_DIR, "go")
+
+ # Check if already downloaded
+ go_bin_dir = os.path.join(go_runtime_dir, "go", "bin")
+ go_executable = (
+ "go.exe" if os_name == "windows" else "go"
+ )
+ if os.path.exists(os.path.join(go_bin_dir, go_executable)):
+ info = (
+ f"Go {GO_VERSION} is already installed at "
+ f"{go_runtime_dir}"
+ )
+ if update_callback:
+ update_callback(f"{info}\n")
+ return go_bin_dir
+
+ try:
+ download_and_extract_runtime(
+ url=url,
+ target_dir=go_runtime_dir,
+ archive_type=ext,
+ checksum_url=checksum_url,
+ update_callback=update_callback,
+ )
+ except (
+ RuntimeDownloadError,
+ RuntimeExtractionError,
+ RuntimeInstallError,
+ ) as e:
+ logger.error(f"Failed to install Go: {e}")
+ if update_callback:
+ update_callback(f"Failed to install Go: {e}\n")
+ return None
+
+ if os.path.exists(os.path.join(go_bin_dir, go_executable)):
+ if update_callback:
+ update_callback(
+ f"Go {GO_VERSION} installed successfully at "
+ f"{go_runtime_dir}\n"
+ )
+ return go_bin_dir
+
+ if update_callback:
+ update_callback(
+ "Failed to install Go. "
+ "If needed, please install it manually.\n"
+ )
+ return None
diff --git a/camel/toolkits/terminal_toolkit/java_runtime.py b/camel/toolkits/terminal_toolkit/java_runtime.py
new file mode 100644
index 000000000..b54ed717e
--- /dev/null
+++ b/camel/toolkits/terminal_toolkit/java_runtime.py
@@ -0,0 +1,230 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+r"""Java runtime auto-installation utilities.
+
+This module provides functionality to detect, download, and configure
+the Java (JDK) runtime. If Java is not already available on the
+system, Eclipse Temurin (Adoptium) JDK 21 LTS is downloaded and
+extracted to ``~/.camel/runtimes/java/``.
+"""
+
+import os
+import shutil
+import subprocess
+from typing import Optional
+
+from camel.logger import get_logger
+
+from .runtime_utils import (
+ ADOPTIUM_DOWNLOAD_URL_TEMPLATE,
+ JAVA_VERSION,
+ RUNTIMES_DIR,
+ ArchiveType,
+ RuntimeDownloadError,
+ RuntimeExtractionError,
+ RuntimeInstallError,
+ SupportedOS,
+ UpdateCallback,
+ download_and_extract_runtime,
+ get_platform_info,
+)
+
+logger = get_logger(__name__)
+
+
+def ensure_java_available(
+ update_callback: UpdateCallback = None,
+) -> Optional[str]:
+ r"""Ensure Java (JDK) is available, downloading if necessary.
+
+ Checks if Java is already installed on the system. If not,
+ downloads Eclipse Temurin (Adoptium) JDK 21 LTS for the current
+ platform and extracts it to ``~/.camel/runtimes/java/``.
+
+ Args:
+ update_callback (Callable[[str], None], optional): Callback
+ function to receive status updates.
+ (default: :obj:`None`)
+
+ Returns:
+ Optional[str]: The JAVA_HOME directory path, or ``None``
+ if Java could not be made available.
+ """
+ # Check if Java is already available on PATH
+ existing_java = shutil.which("java")
+ existing_javac = shutil.which("javac")
+ if existing_java is not None and existing_javac is not None:
+ try:
+ result = subprocess.run(
+ ["java", "-version"],
+ check=False,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ javac_result = subprocess.run(
+ ["javac", "-version"],
+ check=False,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ # java -version outputs to stderr
+ version_output = (
+ result.stderr.strip() or result.stdout.strip()
+ )
+ if (
+ result.returncode == 0
+ and javac_result.returncode == 0
+ ):
+ info = (
+ f"Java is already available: "
+ f"{version_output}"
+ )
+ if update_callback:
+ update_callback(f"{info}\n")
+ return os.path.dirname(
+ os.path.dirname(existing_java)
+ )
+ except Exception:
+ pass
+
+ # Java not found, attempt auto-install
+ if update_callback:
+ update_callback(
+ f"Java not found, installing Adoptium Temurin "
+ f"JDK {JAVA_VERSION} LTS...\n"
+ )
+
+ try:
+ os_name, arch = get_platform_info()
+ except RuntimeError as e:
+ if update_callback:
+ update_callback(
+ f"Cannot auto-install Java: {e}\n"
+ )
+ return None
+
+ # Map arch/OS names for Adoptium API
+ adoptium_arch = "x64" if arch == "amd64" else arch
+ adoptium_os = "mac" if os_name == "darwin" else os_name
+
+ # Construct Adoptium API URL from template
+ url = ADOPTIUM_DOWNLOAD_URL_TEMPLATE.format(
+ version=JAVA_VERSION,
+ os_name=adoptium_os,
+ arch=adoptium_arch,
+ )
+
+ java_runtime_dir = os.path.join(RUNTIMES_DIR, "java")
+ archive_type: ArchiveType = (
+ "zip" if os_name == "windows" else "tar.gz"
+ )
+
+ # Check if already downloaded
+ java_home = _find_java_home(java_runtime_dir, os_name)
+ if java_home:
+ info = (
+ f"Java JDK is already installed at {java_home}"
+ )
+ if update_callback:
+ update_callback(f"{info}\n")
+ return java_home
+
+ try:
+ download_and_extract_runtime(
+ url=url,
+ target_dir=java_runtime_dir,
+ archive_type=archive_type,
+ update_callback=update_callback,
+ )
+ except (
+ RuntimeDownloadError,
+ RuntimeExtractionError,
+ RuntimeInstallError,
+ ) as e:
+ logger.error(f"Failed to install Java: {e}")
+ if update_callback:
+ update_callback(f"Failed to install Java: {e}\n")
+ return None
+
+ java_home = _find_java_home(java_runtime_dir, os_name)
+ if java_home:
+ if update_callback:
+ update_callback(
+ f"Adoptium Temurin JDK {JAVA_VERSION} installed "
+ f"successfully at {java_home}\n"
+ )
+ return java_home
+
+ if update_callback:
+ update_callback(
+ "Failed to install Java. "
+ "If needed, please install it manually.\n"
+ )
+ return None
+
+
+def _find_java_home(
+ java_runtime_dir: str, os_name: SupportedOS
+) -> Optional[str]:
+ r"""Find the JAVA_HOME directory within the runtime directory.
+
+ Adoptium extracts to a versioned directory like
+ ``jdk-21.0.x+y/``. This helper scans for it.
+
+ Args:
+ java_runtime_dir (str): The parent directory where Java was
+ extracted.
+ os_name (SupportedOS): The operating system name.
+
+ Returns:
+ Optional[str]: The path to JAVA_HOME, or None if not found.
+ """
+ if not os.path.exists(java_runtime_dir):
+ return None
+
+ java_executable = (
+ "java.exe" if os_name == "windows" else "java"
+ )
+
+ for entry in os.listdir(java_runtime_dir):
+ entry_path = os.path.join(java_runtime_dir, entry)
+ if not os.path.isdir(entry_path):
+ continue
+
+ # On macOS, the structure is
+ # jdk-xxx/Contents/Home/bin/java
+ if os_name == "darwin":
+ java_path = os.path.join(
+ entry_path,
+ "Contents",
+ "Home",
+ "bin",
+ java_executable,
+ )
+ if os.path.exists(java_path):
+ return os.path.join(
+ entry_path, "Contents", "Home"
+ )
+
+ # On Linux/Windows, the structure is jdk-xxx/bin/java
+ java_path = os.path.join(
+ entry_path, "bin", java_executable
+ )
+ if os.path.exists(java_path):
+ return entry_path
+
+ return None
diff --git a/camel/toolkits/terminal_toolkit/runtime_utils.py b/camel/toolkits/terminal_toolkit/runtime_utils.py
new file mode 100644
index 000000000..0123aa0a6
--- /dev/null
+++ b/camel/toolkits/terminal_toolkit/runtime_utils.py
@@ -0,0 +1,262 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+r"""Shared utilities, constants, and types for runtime auto-installation.
+
+This module provides common infrastructure used by the Go and Java
+runtime installers, including platform detection, binary download
+and extraction, and shared type definitions.
+"""
+
+import hashlib
+import os
+import platform
+import shutil
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from enum import Enum
+from typing import Callable, Literal, Optional
+
+from camel.logger import get_logger
+
+logger = get_logger(__name__)
+
+# ── Type Aliases ─────────────────────────────────────────────────────
+
+SupportedOS = Literal["linux", "darwin", "windows"]
+SupportedArch = Literal["amd64", "arm64"]
+ArchiveType = Literal["tar.gz", "zip"]
+UpdateCallback = Optional[Callable[[str], None]]
+
+
+class Runtime(str, Enum):
+ r"""Supported language runtimes."""
+ GO = "go"
+ JAVA = "java"
+
+# ── Constants ────────────────────────────────────────────────────────
+
+GO_VERSION = "1.23.6"
+JAVA_VERSION = "21"
+RUNTIMES_DIR = os.path.join(
+ os.path.expanduser("~"), ".camel", "runtimes"
+)
+
+# ── URL Templates ────────────────────────────────────────────────────
+
+GO_DOWNLOAD_URL_TEMPLATE = (
+ "https://go.dev/dl/go{version}.{os_name}-{arch}.{ext}"
+)
+GO_CHECKSUM_URL_TEMPLATE = (
+ "https://go.dev/dl/go{version}.{os_name}-{arch}.{ext}.sha256"
+)
+ADOPTIUM_DOWNLOAD_URL_TEMPLATE = (
+ "https://api.adoptium.net/v3/binary/latest/"
+ "{version}/ga/{os_name}/{arch}/jdk/hotspot/normal/eclipse"
+)
+
+# ── Architecture & OS Mappings ───────────────────────────────────────
+
+_MACHINE_TO_ARCH: dict[str, SupportedArch] = {
+ "x86_64": "amd64",
+ "amd64": "amd64",
+ "aarch64": "arm64",
+ "arm64": "arm64",
+}
+
+_SUPPORTED_OS_SET: set[str] = {"linux", "darwin", "windows"}
+
+
+# ── Exceptions ───────────────────────────────────────────────────────
+
+
+class RuntimeDownloadError(Exception):
+ r"""Raised when a runtime binary download fails."""
+
+
+class RuntimeExtractionError(Exception):
+ r"""Raised when extracting a downloaded runtime archive fails."""
+
+
+class RuntimeInstallError(Exception):
+ r"""Raised when a runtime installation fails for any reason."""
+
+
+# ── Platform Detection ───────────────────────────────────────────────
+
+
+def get_platform_info() -> tuple[SupportedOS, SupportedArch]:
+ r"""Detect the current OS and architecture for binary downloads.
+
+ Returns:
+ tuple[SupportedOS, SupportedArch]: A tuple of (os_name, arch)
+ suitable for constructing download URLs.
+
+ Raises:
+ RuntimeError: If the OS or architecture is unsupported.
+ """
+ os_name = platform.system().lower()
+ if os_name not in _SUPPORTED_OS_SET:
+ raise RuntimeError(
+ f"Unsupported operating system: {os_name}"
+ )
+
+ machine = platform.machine().lower()
+ arch = _MACHINE_TO_ARCH.get(machine)
+ if arch is None:
+ raise RuntimeError(f"Unsupported architecture: {machine}")
+
+ return os_name, arch # type: ignore[return-value]
+
+
+# ── Download & Extraction ────────────────────────────────────────────
+
+
+def download_and_extract_runtime(
+ url: str,
+ target_dir: str,
+ archive_type: ArchiveType = "tar.gz",
+ checksum_url: Optional[str] = None,
+ update_callback: UpdateCallback = None,
+) -> None:
+ r"""Download and extract a runtime binary archive.
+
+ Args:
+ url (str): URL of the archive to download.
+ target_dir (str): Directory to extract the archive into.
+ archive_type (ArchiveType): Type of archive, either
+ ``'tar.gz'`` or ``'zip'``.
+ (default: :obj:`tar.gz`)
+ checksum_url (str, optional): URL to a SHA256 checksum file
+ for verification. (default: :obj:`None`)
+ update_callback (Callable[[str], None], optional): Callback
+ function to receive status updates.
+ (default: :obj:`None`)
+
+ Raises:
+ RuntimeDownloadError: If the download fails.
+ RuntimeExtractionError: If the archive extraction fails.
+ RuntimeInstallError: If the installation fails for any
+ other reason.
+ """
+ tmp_file = None
+ try:
+ os.makedirs(target_dir, exist_ok=True)
+
+ # Download to a temporary file
+ suffix = ".tar.gz" if archive_type == "tar.gz" else ".zip"
+ fd, tmp_file = tempfile.mkstemp(suffix=suffix)
+ os.close(fd)
+
+ if update_callback:
+ update_callback(f"Downloading from {url}...\n")
+
+ # Use a proper User-Agent header to avoid 403 errors
+ # from CDNs that block Python's default User-Agent
+ req = urllib.request.Request(
+ url,
+ headers={"User-Agent": "camel-ai/runtime-installer"},
+ )
+ with urllib.request.urlopen(req) as response:
+ with open(tmp_file, 'wb') as out_file:
+ shutil.copyfileobj(response, out_file)
+
+ # Verify checksum if provided
+ if checksum_url:
+ _verify_checksum(tmp_file, checksum_url, update_callback)
+
+ # Extract the archive
+ if update_callback:
+ update_callback(f"Extracting to {target_dir}...\n")
+
+ if archive_type == "tar.gz":
+ with tarfile.open(tmp_file, 'r:gz') as tar:
+ tar.extractall(path=target_dir)
+ else:
+ with zipfile.ZipFile(tmp_file, 'r') as zf:
+ zf.extractall(path=target_dir)
+
+ except urllib.error.URLError as e:
+ raise RuntimeDownloadError(
+ f"Failed to download from {url}: {e}"
+ ) from e
+ except (tarfile.TarError, zipfile.BadZipFile) as e:
+ raise RuntimeExtractionError(
+ f"Failed to extract archive: {e}"
+ ) from e
+ except (RuntimeDownloadError, RuntimeExtractionError):
+ raise
+ except Exception as e:
+ raise RuntimeInstallError(
+ f"Runtime installation failed: {e}"
+ ) from e
+ finally:
+ if tmp_file and os.path.exists(tmp_file):
+ try:
+ os.remove(tmp_file)
+ except OSError:
+ pass
+
+
+def _verify_checksum(
+ file_path: str,
+ checksum_url: str,
+ update_callback: UpdateCallback = None,
+) -> None:
+ r"""Verify the SHA256 checksum of a downloaded file.
+
+ Args:
+ file_path (str): Path to the file to verify.
+ checksum_url (str): URL to the SHA256 checksum file.
+ update_callback (Callable[[str], None], optional): Callback
+ function to receive status updates.
+ (default: :obj:`None`)
+ """
+ try:
+ if update_callback:
+ update_callback("Verifying checksum...\n")
+
+ req = urllib.request.Request(
+ checksum_url,
+ headers={"User-Agent": "camel-ai/runtime-installer"},
+ )
+ with urllib.request.urlopen(req) as response:
+ checksum_data = response.read().decode('utf-8')
+
+ sha256 = hashlib.sha256()
+ with open(file_path, 'rb') as f:
+ for chunk in iter(lambda: f.read(8192), b''):
+ sha256.update(chunk)
+ actual_hash = sha256.hexdigest()
+
+ if actual_hash not in checksum_data:
+ raise RuntimeDownloadError(
+ "Checksum verification failed! "
+ "Download may be corrupted."
+ )
+
+ if update_callback:
+ update_callback("Checksum verified successfully.\n")
+ except RuntimeDownloadError:
+ raise
+ except Exception as e:
+ logger.warning(f"Checksum verification skipped: {e}")
+ if update_callback:
+ update_callback(
+ f"Warning: Checksum verification skipped: "
+ f"{e}\n"
+ )
diff --git a/camel/toolkits/terminal_toolkit/terminal_toolkit.py b/camel/toolkits/terminal_toolkit/terminal_toolkit.py
index 76a7fd653..3cc713176 100644
--- a/camel/toolkits/terminal_toolkit/terminal_toolkit.py
+++ b/camel/toolkits/terminal_toolkit/terminal_toolkit.py
@@ -27,6 +27,13 @@ from camel.logger import get_logger
from camel.toolkits import manual_timeout
from camel.toolkits.base import BaseToolkit
from camel.toolkits.function_tool import FunctionTool
+from camel.toolkits.terminal_toolkit.go_runtime import (
+ ensure_go_available,
+)
+from camel.toolkits.terminal_toolkit.java_runtime import (
+ ensure_java_available,
+)
+from camel.toolkits.terminal_toolkit.runtime_utils import Runtime
from camel.toolkits.terminal_toolkit.utils import (
check_nodejs_availability,
clone_current_environment,
@@ -88,6 +95,11 @@ class TerminalToolkit(BaseToolkit):
environment for local execution. Defaults to False.
install_dependencies (List): A list of user specified libraries
to install.
+ enable_other_runtimes (list[Runtime]): List of additional
+ language runtimes to auto-install. Supported values are
+ ``Runtime.GO`` and ``Runtime.JAVA``. If empty (the default),
+ only the Python runtime is configured. Example:
+ ``enable_other_runtimes=[Runtime.GO, Runtime.JAVA]``.
"""
def __init__(
@@ -101,6 +113,7 @@ class TerminalToolkit(BaseToolkit):
allowed_commands: Optional[List[str]] = None,
clone_current_env: bool = False,
install_dependencies: Optional[List[str]] = None,
+ enable_other_runtimes: list[Runtime] | None = None,
):
# auto-detect if running inside a CAMEL runtime container
# when inside a runtime, use local execution (already sandboxed)
@@ -165,6 +178,12 @@ class TerminalToolkit(BaseToolkit):
self.initial_env_path: Optional[str] = None
self.python_executable = sys.executable
self.install_dependencies = install_dependencies or []
+ self.enable_other_runtimes: set[Runtime] = set(
+ enable_other_runtimes or []
+ )
+ # Instance-level env vars for runtimes (avoids mutating
+ # process-global os.environ)
+ self._runtime_env_vars: dict[str, str] = {}
self.log_dir = os.path.abspath(
session_logs_dir or os.path.join(self.working_dir, "terminal_logs")
@@ -272,6 +291,9 @@ class TerminalToolkit(BaseToolkit):
self.python_executable = os.path.join(
self.cloned_env_path, "bin", "python"
)
+
+ # Set up other language runtimes if requested
+ self._setup_optional_runtimes(update_callback)
else:
logger.info(
"[ENV CLONE] Failed to create cloned environment, "
@@ -390,12 +412,63 @@ class TerminalToolkit(BaseToolkit):
# Check Node.js availability
check_nodejs_availability(update_callback)
+
+ # Set up other language runtimes if requested
+ self._setup_optional_runtimes(update_callback)
else:
logger.info(
"[ENV INIT] Failed to create initial environment, "
"using system Python"
)
+ def _setup_optional_runtimes(self, update_callback):
+ r"""Set up Go and/or Java runtimes if requested.
+
+ Stores runtime paths in ``self._runtime_env_vars`` instead of
+ mutating the process-global ``os.environ``, so only commands
+ launched by this toolkit instance see the extra paths.
+
+ Args:
+ update_callback: Callback for status messages.
+ """
+ # Check Go availability if enabled
+ if Runtime.GO in self.enable_other_runtimes:
+ go_path = ensure_go_available(update_callback)
+ if go_path:
+ current = self._runtime_env_vars.get(
+ "PATH", os.environ.get("PATH", "")
+ )
+ self._runtime_env_vars["PATH"] = (
+ go_path + os.pathsep + current
+ )
+
+ # Check Java availability if enabled
+ if Runtime.JAVA in self.enable_other_runtimes:
+ java_home = ensure_java_available(update_callback)
+ if java_home:
+ self._runtime_env_vars["JAVA_HOME"] = java_home
+ java_bin = os.path.join(java_home, "bin")
+ current = self._runtime_env_vars.get(
+ "PATH", os.environ.get("PATH", "")
+ )
+ self._runtime_env_vars["PATH"] = (
+ java_bin + os.pathsep + current
+ )
+
+ def _get_env_vars(self) -> dict[str, str]:
+ r"""Build the environment dict for subprocess calls.
+
+ Merges the process environment with instance-level runtime
+ paths and sets ``PYTHONUNBUFFERED=1`` for real-time output.
+
+ Returns:
+ dict[str, str]: Environment variables for subprocess.
+ """
+ env = os.environ.copy()
+ env.update(self._runtime_env_vars)
+ env["PYTHONUNBUFFERED"] = "1"
+ return env
+
def _get_venv_path(self) -> Optional[str]:
r"""Get the virtual environment path if available."""
if self.cloned_env_path and os.path.exists(self.cloned_env_path):
@@ -677,8 +750,7 @@ class TerminalToolkit(BaseToolkit):
try:
if not self.use_docker_backend:
- env_vars = os.environ.copy()
- env_vars["PYTHONUNBUFFERED"] = "1"
+ env_vars = self._get_env_vars()
proc = subprocess.Popen(
command,
stdout=subprocess.PIPE,
@@ -839,8 +911,7 @@ class TerminalToolkit(BaseToolkit):
# Without this, Python subprocesses buffer output (4KB buffer)
# and shell_view() won't see output until buffer fills or process
# exits
- env_vars = os.environ.copy()
- env_vars["PYTHONUNBUFFERED"] = "1"
+ env_vars = self._get_env_vars()
docker_env = {"PYTHONUNBUFFERED": "1"}
# Check and create session atomically to prevent race condition
diff --git a/camel/toolkits/terminal_toolkit/utils.py b/camel/toolkits/terminal_toolkit/utils.py
index 7ed75df38..d78a77270 100644
--- a/camel/toolkits/terminal_toolkit/utils.py
+++ b/camel/toolkits/terminal_toolkit/utils.py
@@ -840,3 +840,4 @@ def check_nodejs_availability(update_callback=None) -> Tuple[bool, str]:
update_callback(f"Note: {info}.\n")
logger.warning(f"Failed to check Node.js: {e}")
return False, info
+
diff --git a/examples/toolkits/terminal_toolkit_runtimes.py b/examples/toolkits/terminal_toolkit_runtimes.py
new file mode 100644
index 000000000..b01ec08ef
--- /dev/null
+++ b/examples/toolkits/terminal_toolkit_runtimes.py
@@ -0,0 +1,173 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+"""
+Example: Using TerminalToolkit with Go and Java runtimes.
+
+This example demonstrates how to enable additional language runtimes
+(Go and Java) in the TerminalToolkit. When enabled, the toolkit
+will auto-detect and, if necessary, download and install the
+specified runtimes.
+
+By default, only the Python runtime is configured. Use the
+``enable_other_runtimes`` parameter to opt in to Go and/or Java
+support.
+"""
+
+import os
+
+from camel.agents import ChatAgent
+from camel.configs import ChatGPTConfig
+from camel.models import ModelFactory
+from camel.toolkits import TerminalToolkit
+from camel.toolkits.terminal_toolkit.runtime_utils import Runtime
+from camel.types import ModelPlatformType, ModelType
+
+# ── Workspace setup ──────────────────────────────────────────────────
+base_dir = os.path.dirname(os.path.abspath(__file__))
+workspace_dir = os.path.join(
+ os.path.dirname(os.path.dirname(base_dir)), "workspace"
+)
+
+# ── System message ───────────────────────────────────────────────────
+sys_msg = (
+ "You are a software engineer with access to a terminal. "
+ "You can compile and run Go and Java programs, as well as "
+ "Python scripts. Use the terminal tools to execute commands."
+)
+
+# ── Model setup ──────────────────────────────────────────────────────
+model_config_dict = ChatGPTConfig(temperature=0.0).as_dict()
+
+model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ model_config_dict=model_config_dict,
+)
+
+# =====================================================================
+# Example 1: Enable Go runtime only
+# =====================================================================
+print("=" * 60)
+print("Example 1: Go runtime")
+print("=" * 60)
+
+tools = TerminalToolkit(
+ working_directory=workspace_dir,
+ enable_other_runtimes=[Runtime.GO],
+).get_tools()
+
+agent = ChatAgent(system_message=sys_msg, model=model, tools=tools)
+agent.reset()
+
+usr_msg = (
+ "Create a Go file named 'hello.go' that prints 'Hello from Go!' "
+ "and then run it using 'go run hello.go'."
+)
+response = agent.step(usr_msg)
+print(str(response.info['tool_calls'])[:1500])
+"""
+===============================================================================
+Expected output (varies by environment):
+The agent will:
+1. Create hello.go with a simple main package that prints "Hello from Go!"
+2. Run the file with `go run hello.go`
+3. Display "Hello from Go!" in the output
+===============================================================================
+"""
+
+# =====================================================================
+# Example 2: Enable Java runtime only
+# =====================================================================
+print("\n" + "=" * 60)
+print("Example 2: Java runtime")
+print("=" * 60)
+
+tools = TerminalToolkit(
+ working_directory=workspace_dir,
+ enable_other_runtimes=[Runtime.JAVA],
+).get_tools()
+
+agent = ChatAgent(system_message=sys_msg, model=model, tools=tools)
+agent.reset()
+
+usr_msg = (
+ "Create a Java file named 'Hello.java' with a class 'Hello' that "
+ "prints 'Hello from Java!', compile it with javac, and run it."
+)
+response = agent.step(usr_msg)
+print(str(response.info['tool_calls'])[:1500])
+"""
+===============================================================================
+Expected output (varies by environment):
+The agent will:
+1. Create Hello.java with a public class that prints "Hello from Java!"
+2. Compile it with `javac Hello.java`
+3. Run it with `java Hello`
+4. Display "Hello from Java!" in the output
+===============================================================================
+"""
+
+# =====================================================================
+# Example 3: Enable both Go and Java runtimes
+# =====================================================================
+print("\n" + "=" * 60)
+print("Example 3: Both Go and Java runtimes")
+print("=" * 60)
+
+tools = TerminalToolkit(
+ working_directory=workspace_dir,
+ enable_other_runtimes=[Runtime.GO, Runtime.JAVA],
+).get_tools()
+
+agent = ChatAgent(system_message=sys_msg, model=model, tools=tools)
+agent.reset()
+
+usr_msg = "Check the installed Go and Java versions."
+response = agent.step(usr_msg)
+print(str(response.info['tool_calls'])[:1500])
+"""
+===============================================================================
+Expected output (varies by environment):
+The agent will:
+1. Run `go version` → e.g. "go version go1.23.6 linux/amd64"
+2. Run `java -version` → e.g. 'openjdk version "21.0.x"'
+===============================================================================
+"""
+
+# =====================================================================
+# Example 4: Default (no extra runtimes)
+# =====================================================================
+print("\n" + "=" * 60)
+print("Example 4: Default – Python only (no Go/Java)")
+print("=" * 60)
+
+tools = TerminalToolkit(
+ working_directory=workspace_dir,
+ # enable_other_runtimes is omitted → only Python is configured
+).get_tools()
+
+agent = ChatAgent(system_message=sys_msg, model=model, tools=tools)
+agent.reset()
+
+usr_msg = "Check the Python version."
+response = agent.step(usr_msg)
+print(str(response.info['tool_calls'])[:1500])
+"""
+===============================================================================
+Expected output (varies by environment):
+The agent will run `python --version` and display the Python version.
+Go and Java are NOT installed in this configuration.
+===============================================================================
+"""
diff --git a/test/toolkits/test_enable_other_runtimes.py b/test/toolkits/test_enable_other_runtimes.py
new file mode 100644
index 000000000..751fd59b8
--- /dev/null
+++ b/test/toolkits/test_enable_other_runtimes.py
@@ -0,0 +1,235 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+from unittest.mock import patch
+
+from camel.toolkits import TerminalToolkit
+from camel.toolkits.terminal_toolkit.runtime_utils import Runtime
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_java_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_go_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".check_nodejs_availability"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".setup_initial_env_with_uv"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_uv_available"
+)
+def test_default_skips_go_java(
+ mock_uv,
+ mock_setup,
+ mock_node,
+ mock_go,
+ mock_java,
+ tmp_path,
+):
+ """Default enable_other_runtimes=None should NOT call Go/Java."""
+ mock_uv.return_value = (True, "/usr/bin/uv")
+ mock_setup.return_value = True
+
+ toolkit = TerminalToolkit(
+ working_directory=str(tmp_path),
+ )
+ try:
+ mock_go.assert_not_called()
+ mock_java.assert_not_called()
+ finally:
+ toolkit.cleanup()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_java_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_go_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".check_nodejs_availability"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".setup_initial_env_with_uv"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_uv_available"
+)
+def test_go_enabled_calls_go_only(
+ mock_uv,
+ mock_setup,
+ mock_node,
+ mock_go,
+ mock_java,
+ tmp_path,
+):
+ """enable_other_runtimes=[Runtime.GO] should call Go but not Java."""
+ mock_uv.return_value = (True, "/usr/bin/uv")
+ mock_setup.return_value = True
+ mock_go.return_value = "/usr/local/go/bin"
+
+ toolkit = TerminalToolkit(
+ working_directory=str(tmp_path),
+ enable_other_runtimes=[Runtime.GO],
+ )
+ try:
+ mock_go.assert_called_once()
+ mock_java.assert_not_called()
+ finally:
+ toolkit.cleanup()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_java_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_go_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".check_nodejs_availability"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".setup_initial_env_with_uv"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_uv_available"
+)
+def test_both_enabled_calls_both(
+ mock_uv,
+ mock_setup,
+ mock_node,
+ mock_go,
+ mock_java,
+ tmp_path,
+):
+ """enable_other_runtimes=[Runtime.GO, Runtime.JAVA] should call both."""
+ mock_uv.return_value = (True, "/usr/bin/uv")
+ mock_setup.return_value = True
+ mock_go.return_value = "/usr/local/go/bin"
+ mock_java.return_value = "/usr/lib/jvm/jdk-21"
+
+ toolkit = TerminalToolkit(
+ working_directory=str(tmp_path),
+ enable_other_runtimes=[Runtime.GO, Runtime.JAVA],
+ )
+ try:
+ mock_go.assert_called_once()
+ mock_java.assert_called_once()
+ finally:
+ toolkit.cleanup()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_java_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_go_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".clone_current_environment"
+)
+def test_cloned_env_also_sets_up_runtimes(
+ mock_clone,
+ mock_go,
+ mock_java,
+ tmp_path,
+):
+ """clone_current_env=True with enable_other_runtimes should call Go."""
+ mock_clone.return_value = True
+ mock_go.return_value = "/usr/local/go/bin"
+
+ toolkit = TerminalToolkit(
+ working_directory=str(tmp_path),
+ clone_current_env=True,
+ enable_other_runtimes=[Runtime.GO],
+ )
+ try:
+ mock_go.assert_called_once()
+ mock_java.assert_not_called()
+ finally:
+ toolkit.cleanup()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_java_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_go_available"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".check_nodejs_availability"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".setup_initial_env_with_uv"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.terminal_toolkit"
+ ".ensure_uv_available"
+)
+def test_runtime_env_vars_not_in_os_environ(
+ mock_uv,
+ mock_setup,
+ mock_node,
+ mock_go,
+ mock_java,
+ tmp_path,
+):
+ """Runtime paths should be on the instance, not in os.environ."""
+ import os
+
+ mock_uv.return_value = (True, "/usr/bin/uv")
+ mock_setup.return_value = True
+ mock_go.return_value = "/custom/go/bin"
+
+ original_path = os.environ.get("PATH", "")
+
+ toolkit = TerminalToolkit(
+ working_directory=str(tmp_path),
+ enable_other_runtimes=[Runtime.GO],
+ )
+ try:
+ # Process-level PATH should remain unchanged
+ assert os.environ.get("PATH", "") == original_path
+ # Instance should have Go path stored
+ assert "/custom/go/bin" in toolkit._runtime_env_vars.get(
+ "PATH", ""
+ )
+ finally:
+ toolkit.cleanup()
+
diff --git a/test/toolkits/test_go_runtime.py b/test/toolkits/test_go_runtime.py
new file mode 100644
index 000000000..a0d8b73c5
--- /dev/null
+++ b/test/toolkits/test_go_runtime.py
@@ -0,0 +1,101 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+from unittest.mock import MagicMock, patch
+
+from camel.toolkits.terminal_toolkit.go_runtime import (
+ ensure_go_available,
+)
+
+
+@patch("camel.toolkits.terminal_toolkit.go_runtime.subprocess.run")
+@patch("camel.toolkits.terminal_toolkit.go_runtime.shutil.which")
+def test_go_already_installed(mock_which, mock_run):
+ """Should return path without downloading if go is on PATH."""
+ mock_which.return_value = "/usr/local/go/bin/go"
+ mock_run.return_value = MagicMock(
+ returncode=0,
+ stdout="go version go1.23.6 linux/amd64",
+ )
+
+ callback = MagicMock()
+ path = ensure_go_available(update_callback=callback)
+
+ assert path == "/usr/local/go/bin"
+ callback.assert_called()
+ # Should NOT have tried to download
+ assert (
+ "installing"
+ not in str(callback.call_args_list).lower()
+ )
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".download_and_extract_runtime"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".get_platform_info"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".os.path.exists"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".shutil.which"
+)
+def test_go_not_installed_downloads(
+ mock_which,
+ mock_exists,
+ mock_platform,
+ mock_download,
+):
+ """Should attempt download when go is not found."""
+ mock_which.return_value = None
+ mock_platform.return_value = ("linux", "amd64")
+ # First call: check if already downloaded (False)
+ # Second call: check after download (True)
+ mock_exists.side_effect = [False, True]
+
+ callback = MagicMock()
+ path = ensure_go_available(update_callback=callback)
+
+ assert path is not None
+ mock_download.assert_called_once()
+ # Verify the URL uses the template correctly
+ call_kwargs = mock_download.call_args
+ assert (
+ "go1.23.6.linux-amd64.tar.gz"
+ in call_kwargs.kwargs["url"]
+ )
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".get_platform_info"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.go_runtime"
+ ".shutil.which"
+)
+def test_go_unsupported_platform(mock_which, mock_platform):
+ """Should return None for unsupported platforms."""
+ mock_which.return_value = None
+ mock_platform.side_effect = RuntimeError("Unsupported")
+
+ callback = MagicMock()
+ path = ensure_go_available(update_callback=callback)
+
+ assert path is None
diff --git a/test/toolkits/test_java_runtime.py b/test/toolkits/test_java_runtime.py
new file mode 100644
index 000000000..b947aa77b
--- /dev/null
+++ b/test/toolkits/test_java_runtime.py
@@ -0,0 +1,181 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+from unittest.mock import MagicMock, patch
+
+from camel.toolkits.terminal_toolkit.java_runtime import (
+ _find_java_home,
+ ensure_java_available,
+)
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".subprocess.run"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".shutil.which"
+)
+def test_java_already_installed(mock_which, mock_run):
+ """Should return path without downloading if java and javac are on PATH."""
+ mock_which.side_effect = lambda cmd: (
+ "/usr/lib/jvm/jdk-21/bin/java"
+ if cmd == "java"
+ else "/usr/lib/jvm/jdk-21/bin/javac"
+ )
+ mock_run.side_effect = [
+ MagicMock(
+ returncode=0,
+ stderr='openjdk version "21.0.2"',
+ stdout="",
+ ),
+ MagicMock(returncode=0, stderr="", stdout="javac 21.0.2"),
+ ]
+
+ callback = MagicMock()
+ path = ensure_java_available(update_callback=callback)
+
+ assert path == "/usr/lib/jvm/jdk-21"
+ callback.assert_called()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".download_and_extract_runtime"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ "._find_java_home"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".get_platform_info"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".shutil.which"
+)
+def test_java_without_javac_downloads(
+ mock_which,
+ mock_platform,
+ mock_find,
+ mock_download,
+):
+ """Should attempt download when java exists but javac does not."""
+ # java is found but javac is not
+ mock_which.side_effect = lambda cmd: (
+ "/usr/bin/java" if cmd == "java" else None
+ )
+ mock_platform.return_value = ("linux", "amd64")
+ java_path = "/home/user/.camel/runtimes/java/jdk-21"
+ mock_find.side_effect = [None, java_path]
+
+ callback = MagicMock()
+ path = ensure_java_available(update_callback=callback)
+
+ assert path == java_path
+ mock_download.assert_called_once()
+
+
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".download_and_extract_runtime"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ "._find_java_home"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".get_platform_info"
+)
+@patch(
+ "camel.toolkits.terminal_toolkit.java_runtime"
+ ".shutil.which"
+)
+def test_java_not_installed_downloads(
+ mock_which,
+ mock_platform,
+ mock_find,
+ mock_download,
+):
+ """Should attempt download when java is not found."""
+ mock_which.return_value = None
+ mock_platform.return_value = ("linux", "amd64")
+ # First call: not found; second: found after download
+ java_path = (
+ "/home/user/.camel/runtimes/java/jdk-21"
+ )
+ mock_find.side_effect = [None, java_path]
+
+ callback = MagicMock()
+ path = ensure_java_available(
+ update_callback=callback
+ )
+
+ assert path == java_path
+ mock_download.assert_called_once()
+ # Verify Adoptium URL uses correct mappings
+ call_kwargs = mock_download.call_args
+ call_url = call_kwargs.kwargs["url"]
+ assert call_url.startswith(
+ "https://api.adoptium.net/v3/binary/latest/"
+ "21/ga/linux/x64/"
+ )
+
+
+def test_finds_linux_java_home(tmp_path):
+ """Should find JAVA_HOME on Linux directory structure."""
+ jdk_dir = tmp_path / "jdk-21.0.2+13"
+ bin_dir = jdk_dir / "bin"
+ bin_dir.mkdir(parents=True)
+ (bin_dir / "java").touch()
+
+ result = _find_java_home(str(tmp_path), "linux")
+ assert result == str(jdk_dir)
+
+
+def test_finds_macos_java_home(tmp_path):
+ """Should find JAVA_HOME on macOS directory structure."""
+ jdk_dir = tmp_path / "jdk-21.0.2+13"
+ home_bin = jdk_dir / "Contents" / "Home" / "bin"
+ home_bin.mkdir(parents=True)
+ (home_bin / "java").touch()
+
+ result = _find_java_home(str(tmp_path), "darwin")
+ assert result == str(jdk_dir / "Contents" / "Home")
+
+
+def test_finds_windows_java_home(tmp_path):
+ """Should find JAVA_HOME on Windows directory structure."""
+ jdk_dir = tmp_path / "jdk-21.0.2+13"
+ bin_dir = jdk_dir / "bin"
+ bin_dir.mkdir(parents=True)
+ (bin_dir / "java.exe").touch()
+
+ result = _find_java_home(str(tmp_path), "windows")
+ assert result == str(jdk_dir)
+
+
+def test_returns_none_when_no_java(tmp_path):
+ """Should return None when no JDK is found."""
+ (tmp_path / "some_other_dir").mkdir()
+ result = _find_java_home(str(tmp_path), "linux")
+ assert result is None
+
+
+def test_returns_none_when_dir_missing():
+ """Should return None when the directory doesn't exist."""
+ result = _find_java_home("/nonexistent/path", "linux")
+ assert result is None
diff --git a/test/toolkits/test_runtime_utils.py b/test/toolkits/test_runtime_utils.py
new file mode 100644
index 000000000..d043382d1
--- /dev/null
+++ b/test/toolkits/test_runtime_utils.py
@@ -0,0 +1,67 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+from unittest.mock import patch
+
+import pytest
+
+from camel.toolkits.terminal_toolkit.runtime_utils import (
+ get_platform_info,
+)
+
+
+@patch("camel.toolkits.terminal_toolkit.runtime_utils.platform")
+def test_linux_amd64(mock_platform):
+ mock_platform.system.return_value = "Linux"
+ mock_platform.machine.return_value = "x86_64"
+ os_name, arch = get_platform_info()
+ assert os_name == "linux"
+ assert arch == "amd64"
+
+
+@patch("camel.toolkits.terminal_toolkit.runtime_utils.platform")
+def test_darwin_arm64(mock_platform):
+ mock_platform.system.return_value = "Darwin"
+ mock_platform.machine.return_value = "arm64"
+ os_name, arch = get_platform_info()
+ assert os_name == "darwin"
+ assert arch == "arm64"
+
+
+@patch("camel.toolkits.terminal_toolkit.runtime_utils.platform")
+def test_windows_amd64(mock_platform):
+ mock_platform.system.return_value = "Windows"
+ mock_platform.machine.return_value = "AMD64"
+ os_name, arch = get_platform_info()
+ assert os_name == "windows"
+ assert arch == "amd64"
+
+
+@patch("camel.toolkits.terminal_toolkit.runtime_utils.platform")
+def test_unsupported_os(mock_platform):
+ mock_platform.system.return_value = "FreeBSD"
+ mock_platform.machine.return_value = "x86_64"
+ with pytest.raises(
+ RuntimeError, match="Unsupported operating system"
+ ):
+ get_platform_info()
+
+
+@patch("camel.toolkits.terminal_toolkit.runtime_utils.platform")
+def test_unsupported_arch(mock_platform):
+ mock_platform.system.return_value = "Linux"
+ mock_platform.machine.return_value = "mips"
+ with pytest.raises(
+ RuntimeError, match="Unsupported architecture"
+ ):
+ get_platform_info()