Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

8.6 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.

"""CLI override (--enable-tools/--disable-tools) beats the request, except True on /v1/messages
where the request decides; default applies only when enable_tools is omitted, set only by unsloth
studio run; other launchers leave it unset, so no tools"""

import contextvars
from contextlib import contextmanager
from functools import partial, wraps
from typing import Iterator, Optional

_tool_policy: Optional[bool] = None
_tool_policy_default: Optional[bool] = None

# Per-request hard-off so public surfaces refuse tools even under a CLI `--enable-tools`.
_force_disabled: contextvars.ContextVar[bool] = contextvars.ContextVar(
    "tool_policy_force_disabled", default = False
)


def require_tool_access(
    permission_mode: Optional[str] = None,
    *,
    bypass_permissions: bool = False,
    disable_sandbox: bool = False,
    sandbox_level: Optional[str] = None,
) -> None:
    if permission_mode != "full" and not bypass_permissions and not disable_sandbox:
        if sandbox_level == "low":
            from auth.policy import api_full_access_refused
            if api_full_access_refused():
                from fastapi import HTTPException
                raise HTTPException(
                    status_code = 400,
                    detail = "Sandbox Low (sandbox_level 'low') is off for API keys: Python and Terminal "
                    "run in the OS sandbox. Use sandbox_level 'high', or set "
                    "UNSLOTH_STUDIO_ALLOW_API_FULL_ACCESS=1 on the server to allow it.",
                )
        return
    from auth.policy import api_full_access_refused, full_access_permitted
    from fastapi import HTTPException

    if not full_access_permitted():
        raise HTTPException(
            status_code = 400,
            detail = "Full access is only available to the installation owner.",
        )
    if api_full_access_refused():
        raise HTTPException(
            status_code = 400,
            detail = "Full access (bypass_permissions, permission_mode 'full', disable_sandbox) is off for "
            "API keys: tools run in the sandbox. Use permission_mode 'auto', 'ask' or 'off', or set "
            "UNSLOTH_STUDIO_ALLOW_API_FULL_ACCESS=1 on the server to allow it.",
        )


def normalize_tool_permissions(
    permission_mode: Optional[str], bypass_permissions: bool
) -> tuple[str, bool]:
    require_tool_access(permission_mode, bypass_permissions = bypass_permissions)
    if permission_mode == "full" or bypass_permissions:
        return "full", True
    if permission_mode is None:
        return "auto", False
    if permission_mode not in ("ask", "auto", "off"):
        return "ask", False
    return permission_mode, False


OS_SANDBOXED_TOOLS = frozenset({"python", "terminal"})


SANDBOX_LEVELS = ("high", "low")


def normalize_sandbox_level(value: Optional[str]) -> str:
    """Absent reads as "high"; anything else is a caller bug, so it never silently loosens to "low"."""
    if value is None:
        return "high"
    level = str(value).strip().lower()
    if level not in SANDBOX_LEVELS:
        raise ValueError(f"sandbox_level must be 'high' or 'low', not {value!r}")
    return level


def runs_without_os_sandbox(name: str, sandbox_level: Optional[str]) -> bool:
    """Low: Python and Terminal run on software safeguards only, so they never claim OS isolation."""
    return name in OS_SANDBOXED_TOOLS and sandbox_level == "low"


def off_mode_still_gates(
    name: str,
    sandbox_level: Optional[str] = None,
    session_id: Optional[str] = None,
) -> bool:
    """Whether "off" must still ask for this tool. Cached only; unknown counts as not isolated."""
    if name not in OS_SANDBOXED_TOOLS:
        return False
    if runs_without_os_sandbox(name, sandbox_level):
        return True
    from core.inference.os_sandbox import cached_tool_isolation
    from core.inference.tools import workdir_scan_overran

    return cached_tool_isolation(name) is not True or workdir_scan_overran(session_id)


def tool_call_may_prompt(
    *,
    confirm_tool_calls: bool,
    bypass_permissions: bool,
    permission_mode: Optional[str],
    name: str,
    sandbox_level: Optional[str] = None,
    session_id: Optional[str] = None,
) -> bool:
    """Before the arguments are known: whether a call to ``name`` could stop and ask."""
    if not confirm_tool_calls or bypass_permissions:
        return False
    if permission_mode == "off":
        return off_mode_still_gates(name, sandbox_level, session_id)
    if permission_mode == "auto":
        from core.inference.tools import is_always_safe_tool
        return not is_always_safe_tool(name)
    return True


def needs_tool_confirmation(
    *,
    confirm_tool_calls: bool,
    bypass_permissions: bool,
    permission_mode: Optional[str],
    name: str,
    arguments,
    is_high_risk = None,
    never_needs = None,
    sandbox_level: Optional[str] = None,
    session_id: Optional[str] = None,
) -> bool:
    if is_high_risk is None or never_needs is None:
        from core.inference import tools
        is_high_risk = is_high_risk or tools.is_high_risk_tool_call
        never_needs = never_needs or tools.never_needs_approval
    if not confirm_tool_calls or bypass_permissions or never_needs(name):
        return False
    if permission_mode == "off":
        return off_mode_still_gates(name, sandbox_level, session_id) and _classify(
            is_high_risk, name, arguments, sandbox_level
        )
    if permission_mode == "auto":
        return _classify(is_high_risk, name, arguments, sandbox_level)
    return True


def _classify(is_high_risk, name: str, arguments, sandbox_level: Optional[str]) -> bool:
    """The risk check, told the level: under Low the Terminal's shell is the host's."""
    from core.inference.tools import classifying_under
    with classifying_under(sandbox_level):
        return bool(is_high_risk(name, arguments))


def requires_os_isolation(
    *,
    confirm_tool_calls: bool,
    bypass_permissions: bool,
    permission_mode: Optional[str],
    name: str,
    arguments,
    prompted: bool,
    is_high_risk = None,
    sandbox_level: Optional[str] = None,
) -> bool:
    """Whether the call must launch with tool_execution_mode required (no software fallback); prompted is passed in to avoid a cache race."""
    if prompted or not confirm_tool_calls or bypass_permissions or permission_mode != "off":
        return False
    if name not in OS_SANDBOXED_TOOLS or runs_without_os_sandbox(name, sandbox_level):
        return False
    if is_high_risk is None:
        from core.inference.tools import is_high_risk_tool_call as is_high_risk
    return _classify(is_high_risk, name, arguments, sandbox_level)


def account_tool_stream(stream):
    from utils.account_context import (
        current_account,
        is_owner_context,
        run_as,
        via_api_key_context,
    )

    # An owner API-key request is rebound too: the tool thread must still know it came from an API key.
    if is_owner_context() and not via_api_key_context():
        return stream
    account = current_account()

    @wraps(stream)
    def scoped(invoke, *args, **kwargs):
        return stream(partial(run_as, account, invoke), *args, **kwargs)

    return scoped


def get_tool_policy() -> Optional[bool]:
    if _force_disabled.get():
        return False
    return _tool_policy


def get_tool_policy_default() -> Optional[bool]:
    """Fallback for an omitted `enable_tools`: None unless `unsloth studio run` installed one, else off."""
    if _force_disabled.get():
        return False
    return _tool_policy_default


def conversation_recall_allowed() -> bool:
    """Recall reads only this thread's archive: `--disable-tools` keeps it, `tools_force_disabled` does not."""
    return not _force_disabled.get()


@contextmanager
def tools_force_disabled() -> Iterator[None]:
    """Hard-disable server-side tools for the current async context."""
    token = _force_disabled.set(True)
    try:
        yield
    finally:
        _force_disabled.reset(token)


def set_tool_policy(value: Optional[bool]) -> None:
    if value is not None and not isinstance(value, bool):
        raise TypeError(f"tool_policy must be Optional[bool], got {type(value).__name__}")
    global _tool_policy
    _tool_policy = value


def set_tool_policy_default(value: Optional[bool]) -> None:
    if value is not None and not isinstance(value, bool):
        raise TypeError(f"tool_policy_default must be Optional[bool], got {type(value).__name__}")
    global _tool_policy_default
    _tool_policy_default = value


def reset_tool_policy() -> None:
    global _tool_policy, _tool_policy_default
    _tool_policy = None
    _tool_policy_default = None