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.

Studio: let chat call Unsloth's own MCP tools (#15631)

Etherl2d3e8e62090b
diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index 2b43f610eba..3211c79513a 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -23,6 +23,7 @@ from .storage import (
get_user_and_secret,
load_jwt_secret,
save_refresh_token,
+ STUDIO_CHAT_TOOLS_KEY_NAME,
validate_api_key_account,
validate_api_key_with_credential,
verify_refresh_token,
@@ -460,6 +461,8 @@ async def _get_current_credential(
token = credentials.credentials
if token.startswith(API_KEY_PREFIX):
+ from core.inference.load_policy import policy_for_credential
+
verified = await run_in_threadpool(validate_api_key_account, token)
if verified is None:
raise HTTPException(
@@ -467,13 +470,24 @@ async def _get_current_credential(
detail = _invalid_api_key_detail(token),
)
record, secret = verified
+ generation = credential_generation(secret)
# A second lookup by username would bind whoever owns that name after a delete and re-create.
bind_account(
AccountContext(
- record["account_id"], record["username"], record["role"], via_api_key = True
+ record["account_id"],
+ record["username"],
+ record["role"],
+ credential_gen = generation,
+ via_api_key = True,
+ load_policy = policy_for_credential(
+ internal = bool(record.get("key_internal")), key_name = record.get("key_name")
+ ).value,
+ ui_chat = bool(record.get("key_internal"))
+ and record.get("key_name") == STUDIO_CHAT_TOOLS_KEY_NAME,
+ key_id = record.get("key_id"),
)
)
- return record["username"], credential_generation(secret)
+ return record["username"], generation
subject = _decode_subject_without_verification(token)
if subject is None:
@@ -503,7 +517,14 @@ async def _get_current_credential(
status_code = status.HTTP_401_UNAUTHORIZED,
detail = "Invalid token payload",
)
- bind_account(AccountContext(record["account_id"], record["username"], record["role"]))
+ bind_account(
+ AccountContext(
+ record["account_id"],
+ record["username"],
+ record["role"],
+ credential_gen = credential_generation(jwt_secret),
+ )
+ )
# A managed token carrying the desktop marker gets no owner password-change bypass.
is_desktop = payload.get("desktop") is True and record.get("role") == "owner"
if must_change_password and not allow_password_change and not is_desktop:
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index 2f965e34375..79741f5e167 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -1801,6 +1801,9 @@ DEEP_RESEARCH_WORKFLOW_KEY_NAME = "deep-research workflow"
UNSLOTH_START_API_KEY_NAME = "Coding agents (unsloth start)"
# Authority follows this mint stamp, not the name: older Studios let any caller pick the name.
UNSLOTH_START_API_KEY_PURPOSE = "unsloth_start"
+STUDIO_CHAT_TOOLS_KEY_NAME = "Unsloth Studio chat tools"
+# The same key minted for a chat an API key started: it never gets the owner's load-beside pass.
+STUDIO_CHAT_TOOLS_API_KEY_NAME = "Unsloth Studio chat tools (API)"
def create_api_key(
@@ -1951,6 +1954,23 @@ def revoke_internal_api_key(key_id: int) -> bool:
conn.close()
+def delete_internal_api_key(key_id: int) -> bool:
+ """Delete an internal key row and its account copy. For keys minted per call, which would
+ otherwise leave one inactive row behind for every call."""
+ conn = get_connection()
+ try:
+ conn.execute(
+ "DELETE FROM account_api_keys "
+ "WHERE key_hash = (SELECT key_hash FROM api_keys WHERE id = ? AND is_internal = 1)",
+ (key_id,),
+ )
+ cursor = conn.execute("DELETE FROM api_keys WHERE id = ? AND is_internal = 1", (key_id,))
+ conn.commit()
+ return cursor.rowcount > 0
+ finally:
+ conn.close()
+
+
def is_internal_api_key(raw_key: str) -> bool:
"""Memoized: it runs on the event loop per API-key request, and a key's origin never changes."""
if not raw_key.startswith(API_KEY_PREFIX):
@@ -2032,7 +2052,7 @@ def validate_api_key_account(raw_key: str, *, touch: bool = True) -> Optional[Tu
touch = False
cur = conn.execute(
f"""
- SELECT k.id, k.username, k.name, k.purpose, k.is_active, k.expires_at,
+ SELECT k.id, k.username, k.name, k.purpose, k.is_active, k.is_internal, k.expires_at,
u.account_id, u.role, u.is_active AS account_active,
COALESCE(u.account_jwt_secret, u.jwt_secret) AS jwt_secret
FROM api_keys k JOIN auth_user u ON u.username = k.username
@@ -2077,6 +2097,8 @@ def validate_api_key_account(raw_key: str, *, touch: bool = True) -> Optional[Tu
"expires_at": row["expires_at"],
"key_name": row["name"],
"key_purpose": row["purpose"],
+ "key_internal": bool(row["is_internal"]),
+ "key_id": row["id"],
}
return record, secret
finally:
diff --git a/studio/backend/core/inference/ensure_model.py b/studio/backend/core/inference/ensure_model.py
new file mode 100644
index 00000000000..bf01b8886ce
--- /dev/null
+++ b/studio/backend/core/inference/ensure_model.py
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Whether a request may load the model it names, and the coded refusal when it may not.
+
+The routes resolve the target and run the load; this decides, from the request's ``LoadPolicy``
+and what the load would do to the models already loaded, whether it runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Union
+
+from core.inference.load_policy import LoadPolicy, current_load_policy
+
+PAGES = {
+ "llm": "Chat",
+ "chat": "Chat",
+ "tts": "Audio",
+ "audio": "Audio",
+ "stt": "Audio",
+ "image": "Image",
+ "video": "Video",
+}
+_WHAT = {
+ "llm": "chat model",
+ "tts": "text-to-speech model",
+ "audio": "music model",
+ "stt": "speech-to-text model",
+ "image": "image model",
+ "video": "video model",
+}
+
+
+@dataclass(frozen = True)
+class Load:
+ """The load may run; ``beside`` keeps the models already loaded."""
+
+ beside: bool
+
+
+@dataclass(frozen = True)
+class Refusal:
+ code: str
+ status: int
+ message: str
+ kind: Optional[str] = None
+ model: Optional[str] = None
+ page: Optional[str] = None
+
+ def headers(self) -> dict:
+ from utils.api_errors import problem_headers
+ return problem_headers(self.code, kind = self.kind, model = self.model, page = self.page)
+
+ def http_exception(self, path: Optional[str]):
+ """/v1 answers in its envelope; other routes keep a plain detail string, as the UI reads them."""
+ from fastapi import HTTPException
+ from utils.api_errors import error_body_for_path, wants_api_error_envelope
+
+ detail = (
+ error_body_for_path(
+ path, self.message, status = self.status, code = self.code, param = "model"
+ )
+ if isinstance(path, str) and wants_api_error_envelope(path)
+ else self.message
+ )
+ return HTTPException(status_code = self.status, detail = detail, headers = self.headers())
+
+
+Outcome = Union[Load, Refusal]
+
+
+MULTI_MODEL_SETTING = "Keep multiple models loaded (Settings > System > Model memory)"
+# (why it is refused, what the user can change so a retry works), for a credential that may only load beside.
+SWITCH_OFF_FOR_ACCOUNT = (
+ "'Switch model by request' is off for this account",
+ "have the owner turn it on in Settings > API",
+)
+
+
+def _why_it_would_unload() -> tuple[str, Optional[str]]:
+ """Why a load would unload the chat model, and the setting that would keep it, by the current mode."""
+ from utils.multi_model_settings import get_multi_model_mode
+
+ try:
+ mode = get_multi_model_mode()
+ except Exception: # noqa: BLE001 - unread: no setting to name
+ mode = None
+ if mode == "off":
+ return (
+ f"{MULTI_MODEL_SETTING} is Off, so loading it would unload the model serving this chat",
+ "set it to Always",
+ )
+ if mode == "fit":
+ return (
+ f"{MULTI_MODEL_SETTING} is When they fit, and it does not fit beside the model serving "
+ "this chat",
+ "set it to Always",
+ )
+ return ("Loading it here would unload the model serving this chat", None)
+
+
+def needs_user_load(
+ kind: str,
+ model: Optional[str],
+ *,
+ reason: Optional[tuple[str, Optional[str]]] = None,
+) -> Refusal:
+ """``reason`` (why, fix) overrides the multi-model one, for a refusal that setting would not lift."""
+ page = PAGES.get(kind, "Chat")
+ what = _WHAT.get(kind, "model")
+ named = f"The {what} '{model}'" if model else f"A {what}"
+ why, fix = reason or _why_it_would_unload()
+ on_page = f"load it on the {page} page in Unsloth Studio"
+ ask = (
+ f"Ask the user to {fix} and then try again, or to {on_page}."
+ if fix
+ else f"Ask the user to {on_page}, then try again."
+ )
+ return Refusal(
+ code = "needs_user_load",
+ status = 403,
+ message = f"{named} is not loaded. {why}. {ask}",
+ kind = kind,
+ model = model,
+ page = page,
+ )
+
+
+def needs_download(kind: str, model: str) -> Refusal:
+ """A named model that is not on disk, for a credential that may not start a download by loading it."""
+ page = PAGES.get(kind, "Chat")
+ return Refusal(
+ code = "needs_download",
+ status = 404,
+ message = (
+ f"The {_WHAT.get(kind, 'model')} '{model}' is not downloaded yet. Download it first, "
+ f"or ask the user to load it on the {page} page in Unsloth Studio."
+ ),
+ kind = kind,
+ model = model,
+ page = page,
+ )
+
+
+def not_resident_with_switch_off(kind: str, model: str) -> Refusal:
+ """A named model that is not loaded while "Switch model by request" is off."""
+ page = PAGES.get(kind, "Chat")
+ if current_load_policy() is not LoadPolicy.ANY:
+ return needs_user_load(kind, model, reason = SWITCH_OFF_FOR_ACCOUNT)
+ return Refusal(
+ code = "not_loaded",
+ status = 400,
+ message = (
+ f"The {_WHAT.get(kind, 'model')} '{model}' is not loaded, and 'Switch model by "
+ f"request' is off. Load it on the {page} page in Unsloth Studio, or turn on 'Switch "
+ "model by request' under Settings > API to load it from a request."
+ ),
+ kind = kind,
+ model = model,
+ page = page,
+ )
+
+
+def decide_load(
+ *,
+ kind: str,
+ model: Optional[str],
+ beside: bool,
+ unloads_chat: bool,
+ policy: Optional[LoadPolicy] = None,
+) -> Outcome:
+ """``unloads_chat``: the load, run as it would run, unloads a loaded chat model."""
+ policy = current_load_policy() if policy is None else policy
+ if policy is LoadPolicy.NEVER or (policy is LoadPolicy.BESIDE_ONLY and unloads_chat):
+ return needs_user_load(kind, model)
+ return Load(beside = beside)
+
+
+def ensure_load(
+ *,
+ kind: str,
+ model: Optional[str],
+ beside: bool,
+ unloads_chat: bool,
+ path: Optional[str] = None,
+) -> Load:
+ """``decide_load`` that raises its refusal; ``path`` picks the error shape."""
+ outcome = decide_load(kind = kind, model = model, beside = beside, unloads_chat = unloads_chat)
+ if isinstance(outcome, Refusal):
+ raise outcome.http_exception(path)
+ return outcome
+
+
+def media_load_keeps_chat(owner: str) -> bool:
+ """True only when the image or video load provably leaves the chat model loaded."""
+ from core.inference import gpu_arbiter
+ from core.inference.media_switch_backends import load_takes_the_gpu
+ from utils.multi_model_settings import get_multi_model_mode
+
+ if not load_takes_the_gpu():
+ return True
+ # Unpriced (no need_mib), so When they fit counts as evicting: a doubtful case refuses.
+ return not gpu_arbiter.would_evict(owner, policy = get_multi_model_mode())
+
+
+def ensure_media_load(owner: str, kind: str, model: str, *, openai_errors: bool) -> None:
+ """Refuses an image or video switch the request's policy does not allow."""
+ policy = current_load_policy()
+ if policy is LoadPolicy.ANY:
+ return
+ if policy is LoadPolicy.BESIDE_ONLY and media_load_keeps_chat(owner):
+ return
+ from core.inference.media_switch_errors import refuse
+
+ refusal = needs_user_load(kind, model)
+ exc = refuse(
+ refusal.message,
+ status_code = refusal.status,
+ openai_errors = openai_errors,
+ code = refusal.code,
+ )
+ exc.headers = refusal.headers()
+ raise exc
diff --git a/studio/backend/core/inference/generation_ticket.py b/studio/backend/core/inference/generation_ticket.py
index c734bc06086..f41933ad8a6 100644
--- a/studio/backend/core/inference/generation_ticket.py
+++ b/studio/backend/core/inference/generation_ticket.py
@@ -28,12 +28,13 @@ class GenerationTicket:
with self._lock:
return self._stopped or any(event.is_set() for event in self._events)
- def stop(self) -> None:
+ def stop(self) -> bool:
with self._lock:
self._stopped = True
events = list(self._events)
for event in events:
event.set()
+ return bool(events)
class TicketStopEvent(threading.Event):
diff --git a/studio/backend/core/inference/gpu_arbiter.py b/studio/backend/core/inference/gpu_arbiter.py
index 6614f90ded0..97151111e35 100644
--- a/studio/backend/core/inference/gpu_arbiter.py
+++ b/studio/backend/core/inference/gpu_arbiter.py
@@ -71,7 +71,7 @@ class MultiModelAlwaysRefusal(RuntimeError):
def as_http_exception(self, path: Optional[str] = None):
from fastapi import HTTPException
- from utils.api_errors import error_body_for_path
+ from utils.api_errors import error_body_for_path, problem_headers
message = str(self)
detail = (
@@ -79,9 +79,11 @@ class MultiModelAlwaysRefusal(RuntimeError):
if path and path.startswith("/v1/")
else message
)
- return HTTPException(
- status_code = 409, detail = detail, headers = dict(MULTI_MODEL_REFUSAL_HEADERS)
- )
+ headers = {
+ **MULTI_MODEL_REFUSAL_HEADERS,
+ **problem_headers("multi_model_always", kind = self.kind),
+ }
+ return HTTPException(status_code = 409, detail = detail, headers = headers)
def always_refusal_message(
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index bd90a0dca41..5d8bfddfa6d 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -489,10 +489,9 @@ from core.inference.mcp_images import (
is_image_tool as mcp_is_image_tool,
mentions_images as mcp_images_mentioned_in,
)
+from core.inference.tool_facts import repeatable
from core.inference.tool_loop_controller import (
- _WORKSPACE_READ_TOOLS,
BROWSER_TOOL_NAMES,
- REPEATABLE_TOOL_NAMES,
TRUNCATED_TOOL_TURN_MESSAGE,
ToolLoopController,
_reruns_after_new_work,
@@ -500,6 +499,7 @@ from core.inference.tool_loop_controller import (
awaiting_approval_status,
deferred_nudge_text,
provisional_tool_provenance,
+ reads_only,
restore_replayed_tool_results,
with_appended_text,
tool_call_limit_nudge,
@@ -39717,6 +39717,8 @@ class LlamaCppBackend:
and _nudge_enabled(nudge_tool_calls)
and active_tools
and not _render_html_already_done_intent
+ # Telling the user what only they can do is the answer, not a stall.
+ and not tool_controller.awaiting_user
and _reprompt_used < _reprompt_cap
and not _is_reprompt_repeat(_stripped, _last_reprompt_text)
# _stripped is what gets replayed; intent text may be a short tail.
@@ -39944,19 +39946,25 @@ class LlamaCppBackend:
for _tc in tool_calls if deduplicate_tool_calls else ():
_fn = _tc.get("function", {}) or {}
_key = (_fn.get("name", ""), str(_fn.get("arguments", "")))
- if _reruns_after_new_work(_fn.get("name")):
+ # An unseeded generator: two identical calls are two outputs, and each is new work.
+ if _reruns_after_new_work(_fn.get("name")) and repeatable(_fn.get("name")):
+ if not reads_only(_fn.get("name")):
+ _novel_kept += 1
+ _novel_at_last_keep[_key] = _novel_kept
+ _last_workspace_key = _key
+ elif _reruns_after_new_work(_fn.get("name")):
if _key == _last_workspace_key:
continue
if _key in _seen_keys:
if _novel_kept <= _novel_at_last_keep.get(_key, 0):
continue
- elif _fn.get("name") not in _WORKSPACE_READ_TOOLS:
+ elif not reads_only(_fn.get("name")):
_novel_kept += 1
_novel_at_last_keep[_key] = _novel_kept
_last_workspace_key = _key
# A browser call acts on the page as it is then: two scrolls are two scrolls.
# Two identical generate_image calls are two images.
- elif _key in _seen_keys and _fn.get("name") not in REPEATABLE_TOOL_NAMES:
+ elif _key in _seen_keys and not repeatable(_fn.get("name")):
continue
_seen_keys.add(_key)
if len(_deduped) < _MAX_TOOL_CALLS_PER_TURN:
@@ -40064,6 +40072,7 @@ class LlamaCppBackend:
_keys.add(_spec.key)
_next += 1
+ tool_controller.begin_batch()
for _call_index, tc in enumerate(tool_calls or []):
func = tc.get("function", {})
tool_name = func.get("name", "")
diff --git a/studio/backend/core/inference/llama_keepwarm.py b/studio/backend/core/inference/llama_keepwarm.py
index 248bcdad2e0..8112fceb1bf 100644
--- a/studio/backend/core/inference/llama_keepwarm.py
+++ b/studio/backend/core/inference/llama_keepwarm.py
@@ -384,6 +384,16 @@ _current_response_scope: contextvars.ContextVar = contextvars.ContextVar(
)
+def current_request_counted() -> bool:
+ """Whether the request this context serves is in the in-flight count (an external-provider chat drops out)."""
+ scope = _current_response_scope.get()
+ return (
+ isinstance(scope, dict)
+ and bool(scope.get(_TRACKED_SCOPE_KEY))
+ and not scope.get(_UNTRACKED_SCOPE_KEY)
+ )
+
+
def set_current_response_scope(scope) -> None:
_current_response_scope.set(scope if isinstance(scope, dict) else None)
diff --git a/studio/backend/core/inference/load_policy.py b/studio/backend/core/inference/load_policy.py
new file mode 100644
index 00000000000..9380f6f9386
--- /dev/null
+++ b/studio/backend/core/inference/load_policy.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Which model loads a request may cause, decided by the credential that authenticated it."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class LoadPolicy(str, Enum):
+ ANY = "any"
+ # Only a load that cannot unload the model serving chat (one beside it).
+ BESIDE_ONLY = "beside_only"
+ NEVER = "never"
+
+
+def policy_for_credential(*, internal: bool, key_name: object) -> LoadPolicy:
+ """The chat's own tools key acts inside a chat, so it must never unload the model answering it."""
+ from auth.storage import STUDIO_CHAT_TOOLS_API_KEY_NAME, STUDIO_CHAT_TOOLS_KEY_NAME
+
+ if internal and key_name in (STUDIO_CHAT_TOOLS_KEY_NAME, STUDIO_CHAT_TOOLS_API_KEY_NAME):
+ return LoadPolicy.BESIDE_ONLY
+ return LoadPolicy.ANY
+
+
+def owner_chat_loads_beside() -> bool:
+ """The owner's own chat may load beside its model without "Switch model by request": this key
+ can never unload the chat model, and only a signed-in owner session (not an API key) mints it."""
+ from utils.account_context import current_account, is_owner_context
+ return (
+ current_load_policy() is LoadPolicy.BESIDE_ONLY
+ and current_account().ui_chat
+ and is_owner_context()
+ )
+
+
+# Chat tools keys whose calling chat is in the keep-warm count, so a switch may discount exactly that chat.
+_counted_parents: set[int] = set()
+
+
+def note_counted_parent(key_id: int) -> None:
+ _counted_parents.add(key_id)
+
+
+def forget_counted_parent(key_id: int) -> None:
+ _counted_parents.discard(key_id)
+
+
+def parent_chat_counted() -> bool:
+ from utils.account_context import current_account
+ account = current_account()
+ return account.key_id in _counted_parents and current_load_policy() is LoadPolicy.BESIDE_ONLY
+
+
+def current_load_policy() -> LoadPolicy:
+ from utils.account_context import current_account
+ try:
+ return LoadPolicy(current_account().load_policy)
+ except ValueError:
+ # An unknown value is the strictest reading, never a wider one.
+ return LoadPolicy.NEVER
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index 2b22fbc81c7..002a7a5db0a 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -105,6 +105,8 @@ def validate_mcp_address(url: str) -> None:
# Studio's own Decisions server is answered in process; with a local model no request leaves this machine.
if not _managed_mcp_restricted() or (is_studio_decisions(url) and _local_decisions()):
return
+ if is_studio_tools(url):
+ return
if is_stdio(url):
from fastapi import HTTPException
raise HTTPException(
@@ -720,6 +722,22 @@ def is_studio_decisions(url: str) -> bool:
)
+def is_studio_tools(url: str) -> bool:
+ from core.inference.studio_tools_mcp import STUDIO_TOOLS_MCP_PATH
+ from utils.host_policy import is_loopback_host
+
+ try:
+ parts = urlsplit(url)
+ host = parts.hostname or ""
+ except ValueError:
+ return False
+ return (
+ parts.scheme == "http"
+ and is_loopback_host(host)
+ and parts.path.rstrip("/") == STUDIO_TOOLS_MCP_PATH
+ )
+
+
def _client(
url: str,
headers: Optional[dict],
@@ -733,6 +751,11 @@ def _client(
from routes.systemone import decisions_mcp
return Client(decisions_mcp)
+ if is_studio_tools(url):
+ # Listing only: calls go through studio_tools_mcp.call, which binds the caller.
+ from core.inference.studio_tools_mcp import chat_tools_mcp
+ return Client(chat_tools_mcp())
+
if is_stdio(url):
# Belt-and-suspenders: never spawn unless stdio is enabled on this host.
if not stdio_mcp_enabled():
@@ -2293,6 +2316,19 @@ def call_tool_sync(
) -> str:
"""Never raises: failures return as Error strings; OAuth or scope-less HTTP connects once per call."""
+ if is_studio_tools(url):
+ if config_check is not None and not config_check():
+ return f"Error: MCP tool '{name}' failed: MCP server was updated or removed"
+ from core.inference import studio_tools_mcp
+ return studio_tools_mcp.call(
+ name,
+ args,
+ timeout = timeout,
+ cancel_event = cancel_event,
+ ui_resource_uri = ui_resource_uri,
+ config_check = config_check,
+ )
+
async def _one_shot() -> Any:
async with _client(url, headers, use_oauth, **oauth) as client:
# Connecting (OAuth included) can outlast an edit or delete of the server row.
diff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.py
index d4e0f1a90f7..fca40f580be 100644
--- a/studio/backend/core/inference/media_auto_switch.py
+++ b/studio/backend/core/inference/media_auto_switch.py
@@ -328,6 +328,12 @@ async def _gated_start_load(
openai_errors = openai_errors,
):
raise busy(kind, openai_errors)
+ # Again under the gates: a chat model can have loaded since the precheck.
+ from core.inference.ensure_model import ensure_media_load
+
+ await asyncio.to_thread(
+ functools.partial(ensure_media_load, owner, kind, name, openai_errors = openai_errors)
+ )
# Ranked once: the check below and the load it starts both use this card.
planned = media_locality.pin_planned_gpu_ordinal(
await bounded(
@@ -372,7 +378,8 @@ async def _gated_start_load(
openai_errors = openai_errors,
code = "multi_model_always",
)
- refusal.headers = dict(MULTI_MODEL_REFUSAL_HEADERS)
+ # The arbiter's code header names the kind it would unload.
+ refusal.headers = dict(exc.headers or MULTI_MODEL_REFUSAL_HEADERS)
raise refusal from exc
raise
return False
@@ -447,6 +454,13 @@ async def maybe_auto_switch_media_model(
if satisfied_by(await asyncio.to_thread(backend_for(owner).status), name, pick):
return
+ from core.inference.ensure_model import ensure_media_load
+
+ # Before before_switch and the locks: a refused switch must not touch anything.
+ await asyncio.to_thread(
+ functools.partial(ensure_media_load, owner, kind, name, openai_errors = openai_errors)
+ )
+
if before_switch is not None:
await bounded(
asyncio.to_thread(before_switch, pick),
diff --git a/studio/backend/core/inference/media_switch_backends.py b/studio/backend/core/inference/media_switch_backends.py
index 22392150b98..e2ba1890f14 100644
--- a/studio/backend/core/inference/media_switch_backends.py
+++ b/studio/backend/core/inference/media_switch_backends.py
@@ -58,6 +58,12 @@ def chat_busy(count_pending: bool = True) -> bool:
counted = other_inference_request_count(
current_request_counted = True, include_pending = count_pending
)
+ from core.inference.load_policy import parent_chat_counted
+
+ # A chat tools call runs inside its chat, which waits on this switch: that chat, when it is
+ # counted at all (an external-provider chat is not), is never its own blocker.
+ if parent_chat_counted():
+ counted -= 1
# counted once, since a request parked on a switch lock is a waiter inside its own switch
return max(0, counted - max(0, parked - 1)) > 0
except Exception: # noqa: BLE001
diff --git a/studio/backend/core/inference/model_identity.py b/studio/backend/core/inference/model_identity.py
new file mode 100644
index 00000000000..1424be1b0ed
--- /dev/null
+++ b/studio/backend/core/inference/model_identity.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Whether two model names mean the same model: Hub ids fold case, local paths and ref: handles keep it, and repo:variant names one GGUF quant of a repo. Names only; callers probe what is resident."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Iterable, Optional
+
+REF_PREFIX = "ref:"
+# audio.cpp folder ids name a GGUF repo plus a model folder: three segments, still a Hub id.
+AUDIO_CPP_PREFIX = "audio-cpp/audio.cpp-gguf/"
+
+
+def _text(name: Optional[str]) -> str:
+ return str(name or "").strip()
+
+
+def looks_like_path(name: Optional[str], *, strict: bool = False) -> bool:
+ """A host path by its spelling: rooted, home, dot-relative, a backslash, or a drive letter. ``strict`` takes only rooted, home and backslash names, as the OpenAI route has always read them."""
+ if strict:
+ text = str(name)
+ return text.startswith(("/", "~")) or "\\" in text
+ text = _text(name)
+ if text.startswith(("/", "\\", "~", ".")) or "\\" in text:
+ return True
+ return len(text) >= 2 and text[1] == ":" and text[0].isalpha()
+
+
+def on_disk(name: Optional[str]) -> bool:
+ """A relative path (models/Foo.gguf) reads like a Hub id; one that exists is a path."""
+ text = _text(name)
+ if not text:
+ return False
+ try:
+ return Path(text).expanduser().exists()
+ except (OSError, ValueError):
+ return False
+
+
+def is_local(name: Optional[str], *, probe: bool = False) -> bool:
+ """A host path or the ref:<digest> handle of a local model: whole, never repo:variant. ``probe`` also counts a relative name that exists on disk."""
+ text = _text(name)
+ if text.startswith(REF_PREFIX) or looks_like_path(text):
+ return True
+ return probe and on_disk(text)
+
+
+def is_audio_cpp(name: Optional[str]) -> bool:
+ return _text(name).lower().startswith(AUDIO_CPP_PREFIX)
+
+
+def path_key(name: Optional[str]) -> str:
+ """normcase, not lower: on a case-sensitive filesystem /srv/models/Foo and /srv/models/foo differ."""
+ # Replace after normcase: on Windows normcase rewrites '/' to a backslash.
+ return os.path.normcase(_text(name)).replace("\\", "/").rstrip("/")
+
+
+def identity_key(name: Optional[str], *, probe: bool = False) -> str:
+ """A key that groups names of one model; compare two names with same_model, which keeps a path's case when either side is one."""
+ text = _text(name)
+ return path_key(text) if is_local(text, probe = probe) else text.lower()
+
+
+def split_variant(name: Optional[str], *, probe: bool = False) -> tuple[str, Optional[str]]:
+ """``repo:Q4_K_M`` into the repo and the variant. A path's drive letter or colon and a ref: handle are not a variant."""
+ text = _text(name)
+ if is_local(text, probe = probe):
+ return text, None
+ head, sep, tail = text.partition(":")
+ if sep and head and "/" not in tail:
+ return head, tail or None
+ return text, None
+
+
+def same_model(
+ left: Optional[str],
+ right: Optional[str],
+ *,
+ probe: bool = False,
+) -> bool:
+ """Hub ids match in any case; when either name is local both compare as paths."""
+ left, right = _text(left), _text(right)
+ if not left or not right:
+ return False
+ if is_local(left, probe = probe) or is_local(right, probe = probe):
+ return path_key(left) == path_key(right)
+ return left.lower() == right.lower()
+
+
+def same_repo(
+ left: Optional[str],
+ right: Optional[str],
+ *,
+ probe: bool = False,
+) -> bool:
+ """The same model, or two variants of one GGUF repo (repo:variant beside the bare repo)."""
+ if same_model(left, right, probe = probe):
+ return True
+ left_repo, _ = split_variant(left, probe = probe)
+ right_repo, _ = split_variant(right, probe = probe)
+ return same_model(left_repo, right_repo, probe = probe)
+
+
+def matches_any(
+ requested: Optional[str],
+ candidates: Iterable[Optional[str]],
+ *,
+ probe: bool = False,
+) -> bool:
+ return any(same_model(requested, candidate, probe = probe) for candidate in candidates)
+
+
+def same_variant(left: Optional[str], right: Optional[str]) -> bool:
+ """GGUF quants match in any case; no variant on both sides is a match."""
+ return _text(left).lower() == _text(right).lower()
+
+
+def resident_quant_matches(
+ resident_variant: Optional[str],
+ wanted_filename: str,
+ *,
+ settled: bool = True,
+) -> Optional[bool]:
+ """Whether a status that names only a quant holds the GGUF ``wanted_filename``; None when the file names no quant to compare. Status drops a -3.97bpw style suffix, so until the load settles a bpw build is not taken as resident: a sibling build matches its quant too."""
+ from hub.utils.gguf import extract_quant_token, quant_token_with_bpw
+
+ quant = (
+ extract_quant_token(wanted_filename) if wanted_filename.lower().endswith(".gguf") else None
+ )
+ if not quant:
+ return None
+ if not same_variant(resident_variant, quant):
+ return False
+ return settled or quant_token_with_bpw(wanted_filename) == quant
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index e85cf4c1449..5cb7633b5ce 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -61,16 +61,16 @@ from core.inference.mcp_images import (
png_payloads_per_result,
trim_image_turns,
)
+from core.inference.tool_facts import repeatable
from core.inference.tool_loop_controller import (
- _WORKSPACE_READ_TOOLS,
BROWSER_TOOL_NAMES,
- REPEATABLE_TOOL_NAMES,
TRUNCATED_TOOL_TURN_MESSAGE,
ToolLoopController,
_reruns_after_new_work,
append_deferred_nudges,
awaiting_approval_status,
coerce_tool_arguments,
+ reads_only,
restore_replayed_tool_results,
with_appended_text,
status_for_tool,
@@ -1174,6 +1174,8 @@ def run_safetensors_tool_loop(
# Retrieval injected up front is no reason to stop a browser task mid-way.
and (not rag_autoinjected or (browser_turns and already_acted))
and not tool_denied
+ # Telling the user what only they can do is the answer, not a stall.
+ and not tool_controller.awaiting_user
and (browser_turns or not already_acted)
and not is_reprompt_repeat(intent_text, last_reprompt_text)
and is_short_intent_without_action(intent_text)
@@ -1336,19 +1338,25 @@ def run_safetensors_tool_loop(
for _tc in tool_calls if deduplicate_tool_calls else ():
_fn = _tc.get("function", {}) or {}
_key = (_fn.get("name", ""), str(_fn.get("arguments", "")))
- if _reruns_after_new_work(_fn.get("name")):
+ # An unseeded generator: two identical calls are two outputs, and each is new work.
+ if _reruns_after_new_work(_fn.get("name")) and repeatable(_fn.get("name")):
+ if not reads_only(_fn.get("name")):
+ novel_kept += 1
+ novel_at_last_keep[_key] = novel_kept
+ last_workspace_key = _key
+ elif _reruns_after_new_work(_fn.get("name")):
if _key == last_workspace_key:
continue
if _key in seen_keys:
if novel_kept <= novel_at_last_keep.get(_key, 0):
continue
- elif _fn.get("name") not in _WORKSPACE_READ_TOOLS:
+ elif not reads_only(_fn.get("name")):
novel_kept += 1
novel_at_last_keep[_key] = novel_kept
last_workspace_key = _key
# A browser call acts on the page as it is then: two scrolls are two scrolls.
# Two identical generate_image calls are two images.
- elif _key in seen_keys and _fn.get("name") not in REPEATABLE_TOOL_NAMES:
+ elif _key in seen_keys and not repeatable(_fn.get("name")):
continue
seen_keys.add(_key)
if len(deduped) < _MAX_TOOL_CALLS_PER_TURN:
@@ -1381,6 +1389,7 @@ def run_safetensors_tool_loop(
# Where this batch's results start, for the image turn\'s wording.
batch_conversation_start = len(conversation)
+ tool_controller.begin_batch()
for _call_index, tc in enumerate(tool_calls or []):
func = tc.get("function", {}) or {}
tool_name = func.get("name", "") or ""
diff --git a/studio/backend/core/inference/studio_tools_mcp.py b/studio/backend/core/inference/studio_tools_mcp.py
new file mode 100644
index 00000000000..d33ff15bc16
--- /dev/null
+++ b/studio/backend/core/inference/studio_tools_mcp.py
@@ -0,0 +1,370 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The chat's "Unsloth Studio" MCP row: the /mcp tools the CHAT profile offers, answered in process.
+
+Nothing here passes the /mcp gate, so the owner's Agent access switch does not apply and nothing new listens on
+the network. Each call mints an internal API key for the chat's own account and binds it as the tools' caller, so
+every forwarded route is account-scoped and redacted exactly as for an agent's key. The key is deleted when the
+call ends, however it ends."""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import contextvars
+import json
+import threading
+import time
+import weakref
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from core.inference.generation_ticket import GenerationTicket, generation_ticket
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+STUDIO_TOOLS_MCP_PATH = "/mcp/studio-tools"
+# The row's URL. Never dialled: mcp_client answers it in process, whatever port Unsloth Studio runs on.
+STUDIO_TOOLS_MCP_URL = "http://127.0.0.1" + STUDIO_TOOLS_MCP_PATH
+
+_KEY_MAX_S = 6 * 3600
+_KEY_GRACE_S = 300.0
+_DEFAULT_WAIT_S = 3600.0
+# A followed video hands back its job this long before the call's own timeout, which would stop it.
+_FOLLOW_MARGIN_S = 15.0
+_WATCH_POLL_S = 30.0
+_POLL_S = 0.25
+_STOP_WAIT_S = 30.0
+
+_studio_app: Any = None
+_mcp: Any = None
+_mcp_lock = threading.Lock()
+_root_path: contextvars.ContextVar[str] = contextvars.ContextVar(
+ "studio_tools_root_path", default = ""
+)
+
+
+class ChatRootPathMiddleware:
+ """Remembers each HTTP request's root_path for the chat's tool calls, which run off that request."""
+
+ def __init__(self, app: Any) -> None:
+ self.app = app
+
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+ if scope.get("type") != "http":
+ await self.app(scope, receive, send)
+ return
+ token = _root_path.set((scope.get("root_path") or "").rstrip("/"))
+ try:
+ await self.app(scope, receive, send)
+ finally:
+ _root_path.reset(token)
+
+
+def remember_studio_app(app: Any) -> None:
+ global _studio_app
+ _studio_app = app
+
+
+def keyless_caller(account: Any) -> bool:
+ # Keyless API access binds the owner with no credential; minting it the owner's key would widen its scope.
+ return account.via_api_key and account.credential_gen is None
+
+
+def chat_tools_mcp() -> Any:
+ """The chat's own instance, separate from /mcp's, so the external server is untouched."""
+ global _mcp
+ with _mcp_lock:
+ if _mcp is None:
+ from mcp_server import create_studio_mcp
+ from studio_mcp.profile import CHAT
+ _mcp = create_studio_mcp(CHAT)
+ return _mcp
+
+
+def _mint(account: Any, limit: float) -> tuple[str, dict]:
+ from auth import storage
+
+ # The stored username, not the context's: the owner's context may carry the default name.
+ record = storage.get_account_by_id(account.account_id)
+ if record is None:
+ raise RuntimeError("the account is missing or disabled")
+ expires = datetime.now(timezone.utc) + timedelta(seconds = min(limit + _KEY_GRACE_S, _KEY_MAX_S))
+ return storage.create_api_key(
+ username = record.username,
+ name = (
+ storage.STUDIO_CHAT_TOOLS_API_KEY_NAME
+ if account.via_api_key
+ else storage.STUDIO_CHAT_TOOLS_KEY_NAME
+ ),
+ expires_at = expires.isoformat(),
+ internal = True,
+ expect_gen = account.credential_gen,
+ # Pinned to this account, as Deep Research does: the username could name a recreated namesake.
+ account_id = None if record.is_owner else record.account_id,
+ )
+
+
+def _revoke(key_id: int) -> None:
+ from auth import storage
+ try:
+ storage.delete_internal_api_key(key_id)
+ except Exception: # noqa: BLE001 - the key still expires on its own
+ logger.exception("Could not revoke the Unsloth Studio chat tools key %s", key_id)
+
+
+async def _call(
+ caller: Any,
+ name: str,
+ args: dict,
+ ticket: Optional[GenerationTicket] = None,
+ config_check: Any = None,
+ follow_until: Optional[float] = None,
+) -> Any:
+ from fastmcp import Client
+
+ from studio_mcp.caller import bind_caller, reset_caller
+
+ # Bound before connecting: the in-memory server task is started from this task and copies its context.
+ token = bind_caller(caller)
+ try:
+ with generation_ticket(ticket or GenerationTicket()):
+ async with Client(chat_tools_mcp()) as client:
+ # As for a remote row: an edit or delete of the row while connecting stops the call.
+ if config_check is not None and not await asyncio.to_thread(config_check):
+ raise RuntimeError("MCP server was updated or removed while connecting")
+ result = await client.call_tool(name, args, raise_on_error = False)
+ if follow_until is not None:
+ result = await _follow_video(caller, result, follow_until)
+ return result
+ finally:
+ reset_caller(token)
+
+
+async def _follow_video(caller: Any, created: Any, follow_until: float) -> Any:
+ """Follows a chat's video to the end inside its call, as the built-in tool does, so Stop reaches it;
+ read directly (Settings can turn get_job off), and left running past the call's limit."""
+ from studio_mcp import jobs
+ from studio_mcp.loading import WAIT_S_LIMIT
+
+ job = getattr(created, "structured_content", None)
+ job_id = job.get("id") if isinstance(job, dict) else None
+ if getattr(created, "is_error", False) or not job_id:
+ return created
+ result = created
+ while (left := follow_until - time.monotonic()) >= 1:
+ try:
+ read = await jobs.follow(caller, "video", job_id, wait_s = int(min(left, WAIT_S_LIMIT)))
+ except Exception: # noqa: BLE001 - a failed read still leaves the job reference to answer
+ return result
+ result = read
+ status = (getattr(read, "structured_content", None) or {}).get("status")
+ if status not in jobs.RUNNING:
+ break
+ return result
+
+
+# Dataset rows as Unsloth Studio wrote them: a null there is data, and an all-null column is still a column.
+_VERBATIM = frozenset({"data_rows"})
+
+
+def _drop_nulls(value: Any) -> Any:
+ if isinstance(value, dict):
+ return {
+ key: item if key in _VERBATIM else _drop_nulls(item)
+ for key, item in value.items()
+ if item is not None
+ }
+ if isinstance(value, list):
+ return [_drop_nulls(item) for item in value]
+ return value
+
+
+def _without_nulls(result: Any) -> Any:
+ """The model pays for every ``"x":null`` the typed outputs carry, so its JSON text goes without them."""
+ content = []
+ for block in getattr(result, "content", None) or []:
+ text = getattr(block, "text", None) if getattr(block, "type", None) == "text" else None
+ if isinstance(text, str) and text[:1] in "{[":
+ try:
+ parsed = json.loads(text)
+ except ValueError:
+ parsed = None
+ if isinstance(parsed, (dict, list)):
+ block = block.model_copy(
+ update = {
+ "text": json.dumps(
+ _drop_nulls(parsed), ensure_ascii = False, separators = (",", ":")
+ )
+ }
+ )
+ content.append(block)
+ if content:
+ result.content = content
+ structured = getattr(result, "structured_content", None)
+ if isinstance(structured, (dict, list)):
+ result.structured_content = _drop_nulls(structured)
+ return result
+
+
+# Renders earlier calls of a turn left running are stopped by a Stop during a later call of it.
+_turn_tickets: "weakref.WeakKeyDictionary[Any, list[GenerationTicket]]" = (
+ weakref.WeakKeyDictionary()
+)
+_turn_lock = threading.Lock()
+
+
+def _remember(cancel_event: Any, ticket: GenerationTicket) -> None:
+ with _turn_lock:
+ try:
+ _turn_tickets.setdefault(cancel_event, []).append(ticket)
+ except TypeError:
+ pass
+
+
+def _stop_turn(cancel_event: Any) -> None:
+ with _turn_lock:
+ try:
+ tickets = _turn_tickets.pop(cancel_event, [])
+ except TypeError:
+ tickets = []
+ for ticket in tickets:
+ ticket.stop()
+
+
+def _still_running(result: Any) -> bool:
+ from studio_mcp.jobs import RUNNING
+ content = getattr(result, "structured_content", None)
+ return isinstance(content, dict) and content.get("status") in RUNNING
+
+
+def _watch_turn(cancel_event: Any, ticket: GenerationTicket) -> None:
+ """Stops a video still rendering after its call when the chat is stopped: only a Stop or an aborted
+ turn sets this per-request event."""
+ if not callable(getattr(cancel_event, "wait", None)):
+ return
+
+ def watch() -> None:
+ until = time.monotonic() + _KEY_MAX_S
+ while time.monotonic() < until:
+ if cancel_event.wait(_WATCH_POLL_S):
+ ticket.stop()
+ return
+
+ threading.Thread(target = watch, name = "chat-video-stop", daemon = True).start()
+
+
+def _stop(future: Any, ticket: Any) -> None:
+ # Cancelling the route alone leaves an image render running on the GPU; stop it and let the route unwind.
+ if ticket.stop():
+ concurrent.futures.wait([future], timeout = _STOP_WAIT_S)
+ future.cancel()
+
+
+def call(
+ name: str,
+ args: dict,
+ *,
+ timeout: Optional[float],
+ cancel_event: Any = None,
+ ui_resource_uri: Optional[str] = None,
+ config_check: Any = None,
+) -> str:
+ """Run one tool as the current account on the server loop. Never raises: failures are "Error: ..." text."""
+ from core.inference.mcp_client import _flatten_result
+ from core.inference.media_chat_tools import server_loop
+ from studio_mcp.caller import Caller
+ from studio_mcp.profile import CHAT
+ from utils.account_context import arun_as, current_account
+
+ if cancel_event is not None and cancel_event.is_set():
+ _stop_turn(cancel_event)
+ return f"Error: MCP tool '{name}' cancelled"
+ account = current_account()
+ if keyless_caller(account):
+ return f"Error: MCP tool '{name}' failed: Unsloth Studio tools need an API key or a signed-in session."
+ root_path = _root_path.get()
+ app = _studio_app
+ loop = server_loop()
+ if app is None or loop is None:
+ return (
+ f"Error: MCP tool '{name}' failed: Unsloth Studio tools are not ready yet. Try again."
+ )
+ limit = _DEFAULT_WAIT_S if timeout is None or timeout >= 9999 else max(1.0, float(timeout))
+ limit = min(limit, _KEY_MAX_S - _KEY_GRACE_S)
+ try:
+ key, row = _mint(account, limit)
+ except Exception as exc: # noqa: BLE001
+ logger.warning("Could not mint an Unsloth Studio chat tools key: %s", exc)
+ return f"Error: MCP tool '{name}' failed: Unsloth Studio could not authorize this call."
+ from core.inference.llama_keepwarm import current_request_counted
+ from core.inference.load_policy import forget_counted_parent, note_counted_parent
+
+ if current_request_counted():
+ note_counted_parent(row["id"])
+ try:
+ # Minting can outlast an edit or delete of the row.
+ if config_check is not None and not config_check():
+ return f"Error: MCP tool '{name}' failed: MCP server was updated or removed"
+ # A Stop during the mint must not still start the tool.
+ if cancel_event is not None and cancel_event.is_set():
+ _stop_turn(cancel_event)
+ return f"Error: MCP tool '{name}' cancelled"
+ caller = Caller(
+ token = key,
+ account_id = account.account_id,
+ direct_local = False,
+ public_base = root_path,
+ studio_app = app,
+ hf_token = None,
+ profile = CHAT,
+ )
+ # Empty context: another request's fastmcp HTTP request on this thread would outrank the bound caller.
+ ticket = GenerationTicket()
+ if cancel_event is not None:
+ _remember(cancel_event, ticket)
+ deadline = time.monotonic() + limit
+ future = contextvars.Context().run(
+ asyncio.run_coroutine_threadsafe,
+ arun_as(
+ account,
+ _call(
+ caller,
+ name,
+ args,
+ ticket,
+ config_check,
+ **(
+ {"follow_until": deadline - _FOLLOW_MARGIN_S}
+ if name == "generate_video"
+ else {}
+ ),
+ ),
+ ),
+ loop,
+ )
+ while not future.done():
+ if cancel_event is not None and cancel_event.is_set():
+ _stop(future, ticket)
+ _stop_turn(cancel_event)
+ return f"Error: MCP tool '{name}' cancelled"
+ if time.monotonic() >= deadline:
+ _stop(future, ticket)
+ return f"Error: MCP tool '{name}' timed out after {limit:g}s"
+ concurrent.futures.wait([future], timeout = _POLL_S)
+ try:
+ result = future.result()
+ except concurrent.futures.CancelledError:
+ return f"Error: MCP tool '{name}' cancelled"
+ except Exception as exc: # noqa: BLE001
+ logger.exception("Unsloth Studio chat tool %s failed", name)
+ return f"Error: MCP tool '{name}' failed: {exc}"
+ if name == "generate_video" and cancel_event is not None and _still_running(result):
+ _watch_turn(cancel_event, ticket)
+ return _flatten_result(_without_nulls(result), ui_resource_uri)
+ finally:
+ # Here, not on the loop: a cancelled or timed-out call still loses its key at once.
+ forget_counted_parent(row["id"])
+ _revoke(row["id"])
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index 98d7d540270..d9464e47d9d 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -115,13 +115,6 @@ TOOL_ERROR_PREFIXES = (
"No query provided",
)
-DUPLICATE_CALL_NUDGE = (
- "You already made this exact call. Do not repeat the same tool "
- "call. Try a different approach: fetch a URL from previous "
- "results, use Python to process data you already have, or "
- "provide your final answer now."
-)
-
RENDER_HTML_REPEAT_NUDGE = (
"Error: render_html was already called for this response. Do not call "
"render_html again in this response unless the user asks for changes. "
diff --git a/studio/backend/core/inference/tool_facts.py b/studio/backend/core/inference/tool_facts.py
new file mode 100644
index 00000000000..7542bd970a9
--- /dev/null
+++ b/studio/backend/core/inference/tool_facts.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""What the chat tool loop may assume about a tool, keyed by the function name the model calls."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from core.inference.browser_agent import BROWSER_TOOL_NAMES
+from core.inference.media_chat_tools import MEDIA_CHAT_TOOLS
+
+# Never deduplicated: an identical call is new work (the page as it is now, another image).
+REPEATABLE = BROWSER_TOOL_NAMES | MEDIA_CHAT_TOOLS
+_BUILT_IN_READS = frozenset({"view_image"})
+# Unsloth's own tools where an identical call is new work: get_job's answer moves while a job runs,
+# and a generator with no seed draws a fresh one.
+_STUDIO_REPEATS = frozenset({"get_job", "generate_image", "generate_audio", "generate_video"})
+_mcp_polls: set[str] = set()
+# readOnlyHint MCP functions; trusting the hint only makes deduplication stricter.
+_mcp_reads: set[str] = set()
+
+
+# Results blocked until the user acts: telling the user what to do is the answer, not a stall.
+AWAITS_USER = ("[needs_user_load",)
+# Blocked on the user only when the hint says so: an agent with load_model or unload_model can act on it itself.
+AWAITS_USER_WHEN_ASKED = ("[not_loaded", "[multi_model_always")
+ASKS_THE_USER = "Ask the user to "
+
+
+def awaits_user(result: str) -> bool:
+ if any(tag in result for tag in AWAITS_USER):
+ return True
+ return ASKS_THE_USER in result and any(tag in result for tag in AWAITS_USER_WHEN_ASKED)
+
+
+def note_mcp_tool(
+ name: str,
+ tool: Mapping[str, Any],
+ *,
+ studio: bool = False,
+) -> None:
+ if studio and tool.get("name") in _STUDIO_REPEATS:
+ _mcp_polls.add(name)
+ else:
+ _mcp_polls.discard(name)
+ annotations = tool.get("annotations")
+ if isinstance(annotations, Mapping) and annotations.get("readOnlyHint") is True:
+ _mcp_reads.add(name)
+ else:
+ _mcp_reads.discard(name)
+
+
+def repeatable(name: Any) -> bool:
+ return name in REPEATABLE or name in _mcp_polls
+
+
+def reads_only(name: Any) -> bool:
+ return name in _BUILT_IN_READS or name in _mcp_reads
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
index 700837fbf42..32811b05a59 100644
--- a/studio/backend/core/inference/tool_loop_controller.py
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -18,6 +18,7 @@ from core.inference.browser_agent import BROWSER_TOOL_NAMES
from core.inference.llama_tool_schema import unrelaxed
from core.inference.mcp_images import is_image_tool, split_images as split_mcp_images
from core.inference.media_chat_tools import MEDIA_CHAT_TOOLS
+from core.inference.tool_facts import REPEATABLE, awaits_user, reads_only, repeatable
# Provenance the envelope is trusted on; stamped by mcp_client.
MCP_TOOL_PREFIX = "mcp__"
@@ -26,7 +27,7 @@ MCP_TOOL_SEARCH_NAME = "mcp_tool_search"
from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, TOOL_ERROR_PREFIXES
# Never deduplicated: an identical call is new work (the page as it is now, another render).
-REPEATABLE_TOOL_NAMES = BROWSER_TOOL_NAMES | MEDIA_CHAT_TOOLS
+REPEATABLE_TOOL_NAMES = REPEATABLE
_CANONICAL_HEAL_ARG = {
@@ -1059,9 +1060,7 @@ _MCP_TOOL_PREFIX = "mcp__"
# than the card the user is looking at.
_IMAGE_SENTINEL_TOOLS = _SANDBOX_TOOLS | {"code_execution", "generate_image"}
_SOURCE_MAP_TOOLS = frozenset({"search_knowledge_base", "search_conversation"})
-# Invalidated by workspace writes, but reading an image is not new work that licenses a rerun.
-_WORKSPACE_READ_TOOLS = frozenset({"view_image"})
-_WORKSPACE_TOOLS = _SANDBOX_TOOLS | {"edit_file"} | _WORKSPACE_READ_TOOLS
+_WORKSPACE_TOOLS = _SANDBOX_TOOLS | {"edit_file", "view_image"}
def _reruns_after_new_work(tool_name: Any) -> bool:
@@ -1180,10 +1179,9 @@ def _noop_result(reason: NoopReason, tool_name: str) -> str:
return (
f"One earlier request to call tool '{tool_name}' in this batch was "
"not executed because an identical call had already completed "
- "successfully. Do not repeat the same "
- "tool call. Continue with a different enabled tool if that would "
- "materially help, or provide the final answer if you have enough "
- "information."
+ "successfully and nothing has changed since, so its result above still holds. "
+ "Do not repeat the same tool call. Answer from the results you have; call a "
+ "different tool only if it would return information you do not have yet."
)
if reason == "render_html_repeat":
return (
@@ -1258,6 +1256,15 @@ class ToolLoopController:
self._duplicate_noop_limit = max(1, duplicate_noop_limit)
self._history: list[_ToolCallRecord] = []
self._force_final_answer = False
+ self._awaiting_user = False
+
+ @property
+ def awaiting_user(self) -> bool:
+ """A result in the latest batch said only the user can unblock this turn."""
+ return self._awaiting_user
+
+ def begin_batch(self) -> None:
+ self._awaiting_user = False
@property
def history(self) -> tuple[_ToolCallRecord, ...]:
@@ -1355,7 +1362,7 @@ class ToolLoopController:
elif (
self._deduplicate_tool_calls
and key in self._successful_keys
- and tool_name not in REPEATABLE_TOOL_NAMES
+ and not repeatable(tool_name)
and tool_name != MCP_TOOL_SEARCH_NAME
):
# Not the browser tools: each acts on or reads the page as it is now, so a second
@@ -1403,6 +1410,8 @@ class ToolLoopController:
"""Record a real tool execution and return model/frontend payload helpers."""
result_text = result if isinstance(result, str) else str(result)
failed = is_tool_error(result_text)
+ # Sticky for the batch: a parallel call that succeeds does not unblock the user.
+ self._awaiting_user = self._awaiting_user or awaits_user(result_text)
result_text = self._cap_result(result_text, decision.tool_name)
self._history.append(
_ToolCallRecord(
@@ -1416,9 +1425,9 @@ class ToolLoopController:
# otherwise apply the edit twice. Here as well as in the prefilters, which a
# structured batch skips. A failed command can still have written, so it counts too.
if _reruns_after_new_work(decision.tool_name):
- if (
- decision.tool_name not in _WORKSPACE_READ_TOOLS
- and decision.key not in self._workspace_ran
+ # A repeatable writer (an unseeded generator) makes something new on every run.
+ if not reads_only(decision.tool_name) and (
+ decision.key not in self._workspace_ran or repeatable(decision.tool_name)
):
self._workspace_ran.add(decision.key)
self._workspace_novel += 1
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 8b3685eace5..387bfd037d6 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -89,7 +89,9 @@ from core.inference.mcp_client import (
get_cached_resources,
get_cached_tools,
in_failure_cooloff,
+ invalidate_tool_cache,
is_studio_decisions,
+ is_studio_tools,
is_stdio,
list_tools_async,
oauth_client_kwargs,
@@ -103,11 +105,17 @@ from core.inference.mcp_client import (
tool_visible_to,
)
from storage import mcp_servers_db
-from utils.account_context import account_thread, current_account_id, is_owner_context
+from utils.account_context import (
+ account_thread,
+ current_account,
+ current_account_id,
+ is_owner_context,
+)
from utils.current_date_prompt_settings import strip_current_date_update_note
from utils.host_policy import _literal_ip_address
from core.inference.providers import _metadata_host as _provider_metadata_host
from utils import sandbox_memory_limit, tool_result_limit
+from core.inference import tool_facts
from core.inference.tool_confinement import ToolConfinementUnavailable, account_confinement
from pathlib import Path
from utils.paths.storage_roots import RetiredAccountError, ensure_dir
@@ -13102,6 +13110,7 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
logger.warning("Skipping duplicate MCP tool '%s' on '%s'.", raw_name, display)
continue
seen_names.add(name)
+ tool_facts.note_mcp_tool(name, tool, studio = is_studio_tools(server.get("url") or ""))
description = tool.get("description") or ""
if name.split("__", 2)[2] != raw_name:
_MCP_TOOL_ALIASES[name] = raw_name
@@ -13130,7 +13139,14 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
def _enabled_mcp_servers(servers: list[dict]) -> list[dict]:
- enabled = [server for server in servers if server.get("is_enabled")]
+ from core.inference.studio_tools_mcp import keyless_caller
+
+ keyless = keyless_caller(current_account())
+ enabled = [
+ server
+ for server in servers
+ if server.get("is_enabled") and not (keyless and is_studio_tools(server["url"]))
+ ]
if not any(is_studio_decisions(server["url"]) for server in enabled):
return enabled
from utils import systemone_settings
@@ -13173,9 +13189,13 @@ async def get_enabled_mcp_tools(
if not servers:
return []
- # cool-off avoids blocking every send for the full probe timeout when a server is down.
+ # cool-off avoids blocking every send for the full probe timeout when a server is down. The in-process
+ # Unsloth Studio row is re-listed every send, so tool toggles apply at once.
uncached = [
- s for s in servers if get_cached_tools(s["id"]) is None and not in_failure_cooloff(s["id"])
+ s
+ for s in servers
+ if is_studio_tools(s["url"])
+ or (get_cached_tools(s["id"]) is None and not in_failure_cooloff(s["id"]))
]
if uncached:
results = await asyncio.gather(
@@ -13208,6 +13228,9 @@ async def get_enabled_mcp_tools(
)
# Not cached, but a failure is recorded so a down server isn't re-probed during the cool-off.
record_probe_failure(server["id"], bool(fresh.get("use_oauth")))
+ if is_studio_tools(server["url"]):
+ # Never fall back to an older listing that may name a tool since turned off.
+ invalidate_tool_cache(server["id"])
continue
cache_tools(server["id"], payload)
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index a454b85e7ee..bac8384e0c2 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -12557,6 +12557,10 @@ class VideoBackend:
"input_reference cannot be combined with explicit conditioning inputs."
)
cancel = threading.Event()
+ from core.inference.generation_ticket import bind_generation_cancel
+
+ # A chat tools call that is stopped cancels this job too.
+ bind_generation_cancel(cancel)
job_token = object() # this reservation's identity; only its own worker may finalise it
while True:
with self._lock:
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 9f4948aa803..efde23a38a8 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -1275,6 +1275,10 @@ app.router.lifespan_context = combine_lifespans(
app.router.lifespan_context, _studio_mcp_app.lifespan
)
app.mount("/mcp", StudioMcpGate(_studio_mcp_app))
+from core.inference.studio_tools_mcp import ChatRootPathMiddleware, remember_studio_app # noqa: E402
+
+remember_studio_app(app)
+app.add_middleware(ChatRootPathMiddleware)
from loggers.config import LogConfig
from loggers.handlers import LoggingMiddleware
diff --git a/studio/backend/mcp_server.py b/studio/backend/mcp_server.py
index 7bd95c57e83..073869dc61e 100644
--- a/studio/backend/mcp_server.py
+++ b/studio/backend/mcp_server.py
@@ -6,8 +6,11 @@
from __future__ import annotations
from fastmcp import FastMCP
+from fastmcp.tools import Tool
from studio_mcp import prompts
+from studio_mcp.profile import AGENT, CHAT, CallerProfile
+from studio_mcp.surface import render, render_schema
from studio_mcp.tool_access import StudioToolAccess
from studio_mcp.tools import (
audio,
@@ -72,18 +75,49 @@ def tool_names() -> tuple[str, ...]:
return tuple(entry["name"] for entry in tool_catalog())
-def create_studio_mcp() -> FastMCP:
- """Create the Unsloth MCP server and register the high-value tools."""
+def tool_facts() -> dict[str, frozenset[str]]:
+ """What each tool declares about itself (studio_mcp.profile), for the profiles to choose by."""
+ return {
+ name: frozenset(facts)
+ for module in TOOL_MODULES
+ for name, facts in getattr(module, "FACTS", {}).items()
+ }
+
+
+def withheld(profile: CallerProfile = CHAT) -> dict[str, str]:
+ """The tools ``profile`` is never offered, each with the reason."""
+ return profile.withheld(tool_facts())
+
+
+def surface(profile: CallerProfile) -> frozenset[str]:
+ return profile.tools(tool_facts(), tool_names())
+
+
+def create_studio_mcp(profile: CallerProfile = AGENT, exclude: frozenset = frozenset()) -> FastMCP:
+ """The Unsloth MCP server as ``profile`` sees it: its tools minus ``exclude``, their text rendered for that surface."""
mcp = FastMCP("Unsloth Studio", instructions = INSTRUCTIONS)
mcp.add_middleware(StudioToolAccess())
+ tools = surface(profile) - exclude
for module in TOOL_MODULES:
for tool, annotations, *schema in module.TOOLS:
- mcp.tool(
+ if tool.__name__ not in tools:
+ continue
+ built = Tool.from_function(
tool, annotations = annotations, **({"output_schema": schema[0]} if schema else {})
)
+ mcp.add_tool(
+ built.model_copy(
+ update = {
+ "description": render(built.description, tools),
+ "parameters": render_schema(built.parameters, tools),
+ "output_schema": render_schema(built.output_schema, tools),
+ }
+ )
+ )
- for prompt, title in prompts.PROMPTS:
- mcp.prompt(prompt, title = title)
+ if profile.prompts:
+ for prompt, title in prompts.PROMPTS:
+ mcp.prompt(prompt, title = title)
return mcp
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 699c8025799..80bbd151694 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -96,6 +96,7 @@ from utils.api_errors import (
anthropic_error_body,
error_body_for_path,
openai_error_body,
+ problem_headers,
)
from utils.audio_tokens import GGUF_TTS_AUDIO_TYPES as _GGUF_TTS_AUDIO_TYPES
from utils.first_token_timeout import (
@@ -2975,7 +2976,7 @@ _DEFERRED_ERROR_KEY = "_deferred_error"
# Headers a padded error keeps in its body: the status line and headers were already sent.
-_DEFERRED_ERROR_HEADERS = ("x-unsloth-refusal", "retry-after")
+_DEFERRED_ERROR_HEADERS = ("x-unsloth-refusal", "x-unsloth-problem", "retry-after")
def _deferred_error_body(
@@ -6229,6 +6230,8 @@ async def _select_request_tools(
apply_terminal_profile_for_request, tools, getattr(payload, "sandbox_level", None)
)
if mcp_allowed:
+ from core.inference.media_chat_tools import remember_server_loop
+ remember_server_loop(asyncio.get_running_loop())
tools = tools + await get_enabled_mcp_tools()
# Some callers pass lighter payloads that may lack deep_research_armed, so read it with getattr.
if getattr(payload, "deep_research_armed", None):
@@ -10026,6 +10029,29 @@ def _load_alongside_for_request(fastapi_request) -> bool:
return isinstance(scope, dict) and bool(scope.get(_LOAD_ALONGSIDE_SCOPE_KEY))
+# (kind, model) an auto-switch is loading, for the refusal a beside-only load may need.
+_SWITCH_TARGET_SCOPE_KEY = "unsloth.switch_target"
+
+
+def _loads_anything() -> bool:
+ """The request's credential allows any load "Switch model by request" does."""
+ from core.inference.load_policy import LoadPolicy, current_load_policy
+ return current_load_policy() is LoadPolicy.ANY
+
+
+def _require_load_keeps_chat(fastapi_request, request) -> None:
+ """Refuse, for a credential that may only load beside, a load about to unload a chat model."""
+ from core.inference.ensure_model import needs_user_load
+
+ if _loads_anything():
+ return
+ scope = getattr(fastapi_request, "scope", None)
+ target = scope.get(_SWITCH_TARGET_SCOPE_KEY) if isinstance(scope, dict) else None
+ kind, model = target if target else ("llm", public_model_id(request.model_path))
+ path = getattr(getattr(fastapi_request, "url", None), "path", None)
+ raise needs_user_load(kind, model).http_exception(path)
+
+
_NO_AUTO_DOWNLOAD_SCOPE_KEY = "unsloth.no_auto_download"
@@ -10230,6 +10256,22 @@ async def _no_model_loaded_error(
)
+async def _raise_no_model_loaded(
+ base: str, requested_model: Optional[str], fastapi_request: Optional[Request], *, status: int
+) -> None:
+ """Raise :func:`_no_model_loaded_error`'s answer, coded ``not_loaded`` when it is plain."""
+ _status, _detail = await _no_model_loaded_error(
+ base, requested_model, fastapi_request, status = status
+ )
+ # The NPU, keyless and not-downloaded answers are about something else.
+ coded = _detail == _no_model_loaded_detail(base)
+ raise HTTPException(
+ status_code = _status,
+ detail = _detail,
+ headers = problem_headers("not_loaded", kind = "llm") if coded else None,
+ )
+
+
def _auto_download_hf_token(fastapi_request: Optional[Request]) -> Optional[str]:
"""Only the caller's own token, so an API key cannot borrow the owner's private repo access."""
from hub.dependencies import HUB_HF_TOKEN_HEADER, HUB_HF_TOKEN_MAX_LENGTH
@@ -10513,17 +10555,8 @@ def _raise_still_indexing(requested_model: str, fastapi_request) -> None:
def _matches_any(requested: str, candidates) -> bool:
"""Repo ids match case-insensitively; paths stay case-sensitive, or foo.gguf and Foo.gguf merge."""
- lowered = requested.strip().lower()
- for candidate in candidates:
- if not candidate:
- continue
- if _looks_like_local_path(requested) or _looks_like_local_path(candidate):
- if _norm_path(requested) == _norm_path(candidate):
- return True
- continue
- if lowered == str(candidate).strip().lower():
- return True
- return False
+ from core.inference.model_identity import matches_any
+ return matches_any(requested, candidates)
_TRAINED_CHECKPOINT = re.compile(r"checkpoint-\d+")
@@ -10561,17 +10594,13 @@ def _resolve_trained_run_request(request) -> bool:
def _looks_like_local_path(value: str) -> bool:
"""A filesystem path rather than a repo id, so case matters."""
- text = str(value)
- return text.startswith("/") or text.startswith("~") or ":\\" in text or "\\" in text
+ from core.inference.model_identity import looks_like_path
+ return looks_like_path(value, strict = True)
def _norm_path(value: str) -> str:
- """Compare-ready path. normcase, not lower: on a case-sensitive filesystem
- /srv/models/Foo and /srv/models/foo are different models."""
- import os
-
- # Replace after normcase: on Windows normcase rewrites '/' to a backslash.
- return os.path.normcase(str(value)).replace("\\", "/").rstrip("/")
+ from core.inference.model_identity import path_key
+ return path_key(value)
def _resident_quant_is(variant: Optional[str], base: Optional[str] = None) -> bool:
@@ -10778,6 +10807,16 @@ async def _reject_unservable_model(
else message
),
)
+ if (
+ _names_audio_cpp_model(requested_model)
+ and not get_openai_auto_switch_enabled()
+ and not await asyncio.to_thread(_loaded_satisfies, requested_model)
+ ):
+ # The resolver and the Hub id check never see these ids; without this the route
+ # answers a bare "load a model first".
+ from core.inference.ensure_model import not_resident_with_switch_off
+ path = getattr(getattr(fastapi_request, "url", None), "path", None)
+ raise not_resident_with_switch_off("audio", requested_model).http_exception(path)
still_indexing = torn = trained = False
try:
@@ -11017,6 +11056,12 @@ def _own_local_model_for_alias(alias: str) -> Optional[str]:
return None
+def _names_audio_cpp_model(requested_model: Optional[str]) -> bool:
+ """No I/O: an audio.cpp umbrella id, legacy key or id this process has resolved."""
+ from core.inference.audio_cpp_models import looks_like_audio_cpp
+ return isinstance(requested_model, str) and looks_like_audio_cpp(requested_model)
+
+
def _audio_cpp_switch_target(requested_model: Optional[str]) -> Optional[tuple]:
"""Answered from the HF cache alone: an umbrella folder id cannot be keyed by the local index, and a repo GGUF would otherwise reach llama-server."""
from core.inference import audio_cpp_files
@@ -11127,6 +11172,8 @@ async def _auto_switch_npu_model(
# Re-read under the gate: another request may have loaded it while this one waited.
if await asyncio.to_thread(_loaded_satisfies, named_model):
return
+ # Again under the gates: a chat model can have loaded since the preflight.
+ _refuse_unless_any_load("llm", named_model, fastapi_request)
require_no_foreign_generations(path = switch_path)
prior_marker = _get_preview_resident()
loaded_ok = False
@@ -11164,6 +11211,31 @@ async def _auto_switch_npu_model(
_note_switch_waiter(key, -1)
+def _chat_model_resident(*, kept: bool = True) -> bool:
+ """A chat, speech or NPU model is loaded in the primary, or (``kept``) beside it."""
+ if _llama_cpp_backend.is_active or getattr(get_llama_cpp_backend(), "is_loaded", False):
+ return True
+ if _resident_npu_model() is not None or (kept and model_slots.slots):
+ return True
+ return bool(getattr(_peek_inference_backend(), "active_model_name", None))
+
+
+def _refuse_unless_any_load(kind: str, model: Optional[str], fastapi_request) -> None:
+ """A load whose effect on the serving model is not known yet (an NPU swap, a download)."""
+ from core.inference.ensure_model import ensure_load
+
+ if _loads_anything():
+ return
+ path = getattr(getattr(fastapi_request, "url", None), "path", None)
+ ensure_load(
+ kind = kind,
+ model = model,
+ beside = False,
+ unloads_chat = _chat_model_resident(),
+ path = path,
+ )
+
+
def _switch_loads_beside(target_speaks: Callable[[], bool]) -> bool:
"""Under Keep multiple models loaded, a speech model loads beside a text one (or the reverse); the same kind replaces."""
from utils.multi_model_settings import get_multi_model_enabled
@@ -11242,10 +11314,23 @@ async def _maybe_auto_switch_model(
)
# The reload-only sentinel means an omitted model, not a name.
named_model = requested_model if requested_model != _RELOAD_ONLY_MODEL else None
- # The public preview serves its pinned checkpoint only, never a model kept alongside.
- routed = await _route_to_extra_slot(
- None if _auto_switch_opted_out(fastapi_request) else named_model
+ # What a refused load asks the user to load, and on which page.
+ switch_kind = (
+ "audio" if require_audio_workflow == "music" else "tts" if require_speech else "llm"
)
+ held = routed_slot.get()
+ if (
+ requested_model == _RELOAD_ONLY_MODEL
+ and held in model_slots.visible()
+ and not _auto_switch_opted_out(fastapi_request)
+ ):
+ # A later step of a run this task already routed (music speaks through the TTS core).
+ routed = held
+ else:
+ # The public preview serves its pinned checkpoint only, never a model kept alongside.
+ routed = await _route_to_extra_slot(
+ None if _auto_switch_opted_out(fastapi_request) else named_model
+ )
if account_access.managed_account():
if named_model:
await _require_named_model_access(named_model, fastapi_request)
@@ -11352,8 +11437,12 @@ async def _maybe_auto_switch_model(
if claim_resident:
_claim_slot_for_non_preview(fastapi_request)
return
- auto_switch_on = get_openai_auto_switch_enabled() or _model_switch_allowed_for_request(
- fastapi_request
+ from core.inference.load_policy import owner_chat_loads_beside
+
+ auto_switch_on = (
+ get_openai_auto_switch_enabled()
+ or _model_switch_allowed_for_request(fastapi_request)
+ or owner_chat_loads_beside()
)
def _refuse_non_gguf_endpoint() -> None:
@@ -11424,6 +11513,7 @@ async def _maybe_auto_switch_model(
rejection_prefix = rejection_prefix,
request_check = npu_request_check,
)
+ _refuse_unless_any_load("llm", named_model, fastapi_request)
await _auto_switch_npu_model(
named_model, fastapi_request, current_subject, claim_resident = claim_resident
)
@@ -11467,6 +11557,13 @@ async def _maybe_auto_switch_model(
)
# Not on disk. Opt-in: fetch in the background and ask the caller to retry.
if auto_switch_on and not reload_only and not trained:
+ # A beside-only credential downloads with its own tool, not as part of a load.
+ from core.inference.load_policy import LoadPolicy, current_load_policy
+ if current_load_policy() is not LoadPolicy.ANY:
+ from core.inference.ensure_model import needs_download
+ raise needs_download(switch_kind, requested_model).http_exception(
+ getattr(getattr(fastapi_request, "url", None), "path", None)
+ )
await _maybe_auto_download_model(
requested_model,
fastapi_request,
@@ -11830,6 +11927,9 @@ async def _maybe_auto_switch_model(
# start on the model while it is being torn down and replaced.
from utils.multi_model_settings import get_multi_model_enabled
+ from core.inference.ensure_model import ensure_load
+ from core.inference.load_policy import LoadPolicy, current_load_policy
+
# Beside: load_model_gated takes the load gate itself; the primary keeps serving.
beside = await asyncio.to_thread(
_switch_loads_beside,
@@ -11841,8 +11941,12 @@ async def _maybe_auto_switch_model(
is not None
),
) or (
- # The load itself still replaces the loaded model when it does not fit beside it.
- _load_alongside_for_request(fastapi_request)
+ # The load itself still replaces the loaded model when it does not fit
+ # beside it; for a beside-only caller it refuses there instead.
+ (
+ _load_alongside_for_request(fastapi_request)
+ or current_load_policy() is LoadPolicy.BESIDE_ONLY
+ )
and await asyncio.to_thread(get_multi_model_enabled)
)
async with AsyncExitStack() as swap_gates:
@@ -11860,6 +11964,17 @@ async def _maybe_auto_switch_model(
_record_serving_alias()
return
require_no_foreign_generations(path = switch_path)
+ if isinstance(_swap_scope, dict):
+ _swap_scope[_SWITCH_TARGET_SCOPE_KEY] = (switch_kind, named_model)
+ ensure_load(
+ kind = switch_kind,
+ model = named_model,
+ beside = beside,
+ unloads_chat = not beside
+ and not _loads_anything()
+ and await asyncio.to_thread(_chat_model_resident),
+ path = switch_path,
+ )
# Last chance to refuse: held swap gates keep inference and loads from starting before it.
_check_switch_precondition(fastapi_request)
# Order: variant-qualified keys before bare ids, load path before advertised id.
@@ -12418,7 +12533,8 @@ async def _make_room_for_primary(request: LoadRequest, exc, evicted: list) -> Lo
for s in gpu_arbiter.resident_slots(o)
]
raise gpu_residency.need_free_refusal(info if gpus else {}, slots)
- freed = await _free_for_chat(exc, evicted)
+ # A beside-only credential frees image and video models only; a kept chat model stays loaded.
+ freed = await _free_for_chat(exc, evicted, media_only = not _loads_anything())
# Anything freed (an idle video server counts) earns a retry at full size; else llama-server fits what it can.
return request if freed else request.model_copy(update = {"force_alongside": True})
@@ -18041,6 +18157,14 @@ async def load_model_gated(
if not new_slot:
# An auto-switch beside checked before this gate: this load replaces a loaded model.
_check_switch_precondition(fastapi_request)
+ # Reloading a kept slot, or replacing a loaded primary.
+ if not _loads_anything() and (
+ extra is not None
+ or await asyncio.to_thread(
+ functools.partial(_chat_model_resident, kept = False)
+ )
+ ):
+ _require_load_keeps_chat(fastapi_request, request)
# The 409 gate runs inside _load_model_impl, under the lifecycle gate, atomic with teardown.
if new_slot:
reload_gate = None
@@ -18107,7 +18231,8 @@ async def load_model_gated(
continue
if measured and not account_access.managed_account():
# Its Always copy already says nothing is unloaded to make room.
- raise MultiModelAlwaysRefusal(str(exc), kind = "chat") from exc
+ # No kind: it names the model to unload, and this message names none.
+ raise MultiModelAlwaysRefusal(str(exc)) from exc
raise refusal_for(
await asyncio.to_thread(chat_eviction_reports)
) from exc
@@ -18119,6 +18244,7 @@ async def load_model_gated(
# No chat may start on a victim between its pick and teardown.
async with inference_lifecycle_gate() if new_slot else nullcontext():
_check_switch_precondition(fastapi_request)
+ _require_load_keeps_chat(fastapi_request, request)
victims = await asyncio.to_thread(
model_slots.eviction_victims,
extra,
@@ -18145,6 +18271,7 @@ async def load_model_gated(
request = request.model_copy(update = {"force_alongside": True})
continue
# Fits nowhere: replace the active model; its chats refuse first.
+ _require_load_keeps_chat(fastapi_request, request)
routed_slot.set(None)
if not background:
_raise_or_cancel_active_generations(
@@ -19851,6 +19978,8 @@ async def _load_model_impl(
request.engine != "auto" and replacing and bool(model_slots.slots or model_slots.stuck)
)
if retire_kept:
+ # vLLM and SGLang take every kept model down, which a beside-only credential may not do.
+ _require_load_keeps_chat(fastapi_request, request)
_gate_kept_models(request, cancel = False)
if serving and on_reload_confirmed is not None:
on_reload_confirmed(cancel = True)
@@ -22173,7 +22302,9 @@ async def generate_stream(
if not backend.active_model_name:
raise HTTPException(
- status_code = 400, detail = "No model loaded. Call POST /inference/load first."
+ status_code = 400,
+ detail = "No model loaded. Call POST /inference/load first.",
+ headers = problem_headers("not_loaded", kind = "llm"),
)
# Decode image if provided (vision models)
image = None
@@ -22991,13 +23122,16 @@ async def _generate_tts_wav(
voice: Optional[str] = None,
) -> tuple[bytes, int, str, Optional[str]]:
"""Shared core of the three audio generation routes; a named target is budgeted after preflight."""
- # A named target must be budgeted against its own context after preflight.
- if requested_model == _RELOAD_ONLY_MODEL:
- _raise_if_prompt_leaves_no_speech_budget(text)
workflow = (run_inputs or {}).get("workflow")
if workflow == "speak" and (run_inputs or {}).get("audio_inputs"):
# Speaking in a saved voice is cloning, as _audio_request_problem reads it.
workflow = "clone"
+ # A named target, or a speech model kept beside a chat primary, is budgeted against its own
+ # context below; only a primary that will answer is checked before the switch.
+ if requested_model == _RELOAD_ONLY_MODEL and await asyncio.to_thread(
+ _serves_audio_workflow, workflow or "speak"
+ ):
+ _raise_if_prompt_leaves_no_speech_budget(text)
await _maybe_auto_switch_model(
requested_model,
request,
@@ -23015,6 +23149,9 @@ async def _generate_tts_wav(
}
),
)
+ if requested_model == _RELOAD_ONLY_MODEL:
+ # No model named: a speech model kept beside the chat model answers, as the primary would.
+ await _route_to_kept_audio_model(workflow or "speak")
# Recheck once a context exists: before the restore, nothing loaded passes everything.
_raise_if_prompt_leaves_no_speech_budget(text)
@@ -23060,7 +23197,11 @@ async def _generate_tts_wav(
else:
backend = await asyncio.to_thread(get_inference_backend)
if not backend.active_model_name:
- raise HTTPException(status_code = 400, detail = "No model loaded.")
+ raise HTTPException(
+ status_code = 400,
+ detail = "No model loaded.",
+ headers = problem_headers("not_loaded", kind = "audio"),
+ )
model_info = backend.models.get(backend.active_model_name, {})
# A chat model that speaks (LFM3) reads aloud too; the MLX backend has no TTS mode for it.
chat_speaks = (
@@ -23781,6 +23922,59 @@ def _clamp_note(
warnings.append(f"duration_s {asked:g} clamped to {used:g}")
+def _resident_audio_workflows() -> list[str]:
+ """The Audio page workflows the model in this context serves (the primary, or a routed kept slot)."""
+ from core.inference.audio_workflows import status_audio_workflows
+
+ llama = get_llama_cpp_backend()
+ if (
+ getattr(llama, "is_loaded", False)
+ and getattr(llama, "_is_audio", False)
+ and getattr(llama, "_audio_type", None) in _GGUF_TTS_AUDIO_TYPES
+ ):
+ return status_audio_workflows(True, llama._audio_type)
+ backend = _peek_inference_backend()
+ active = getattr(backend, "active_model_name", None)
+ info = (backend.models.get(active) or {}) if active else {}
+ workflows = (
+ list(info.get("audio_workflows") or status_audio_workflows(True, info.get("audio_type")))
+ if info.get("is_audio")
+ else []
+ )
+ # The music route reads audio_music, so it decides music, as it does there.
+ return (
+ [*workflows, "music"] if info.get("audio_music") and "music" not in workflows else workflows
+ )
+
+
+# Workflows a model must name to serve; any other speech model can try the rest (the route checks).
+_DEDICATED_AUDIO_WORKFLOWS = frozenset({"music", "separate", "transcribe"})
+
+
+def _serves_audio_workflow(workflow: str) -> bool:
+ workflows = _resident_audio_workflows()
+ if workflow in _DEDICATED_AUDIO_WORKFLOWS:
+ return workflow in workflows
+ return any(w not in _DEDICATED_AUDIO_WORKFLOWS for w in workflows)
+
+
+async def _route_to_kept_audio_model(workflow: str) -> None:
+ """An omitted model means the loaded one for ``workflow``, which may be kept beside the chat model."""
+ if routed_slot.get() is not None or await asyncio.to_thread(_serves_audio_workflow, workflow):
+ return
+ kept = await asyncio.to_thread(
+ lambda: [
+ s
+ for s in model_slots.visible()
+ if model_slots.in_slot(s, lambda: _serves_audio_workflow(workflow))
+ ]
+ )
+ # Several: which one is not ours to guess; the caller names it.
+ if len(kept) == 1 and model_slots.reserve(kept[0]):
+ routed_slot.set(kept[0])
+ kept[0].last_used = time.monotonic()
+
+
async def _run_music_workflow(
body: AudioRunRequest, request: Request, current_subject: str
) -> AudioRunResponse:
@@ -23799,9 +23993,15 @@ async def _run_music_workflow(
require_speech = True,
require_audio_workflow = "music",
)
+ if not body.model:
+ await _route_to_kept_audio_model("music")
backend = await asyncio.to_thread(get_inference_backend)
if not backend.active_model_name:
- raise HTTPException(status_code = 400, detail = "Load a music model first.")
+ raise HTTPException(
+ status_code = 400,
+ detail = "Load a music model first.",
+ headers = problem_headers("not_loaded", kind = "audio"),
+ )
model_info = backend.models.get(backend.active_model_name, {}) or {}
label = _audio_model_label(_orchestrator_public_model_id(backend))
rules = model_info.get("audio_music")
@@ -24148,8 +24348,12 @@ async def _dispatch_audio_run(
raise HTTPException(
status_code = 409, detail = "Another audio run is using this cancel_id."
)
+ from core.inference.generation_ticket import bind_generation_cancel
+
token = _AUDIO_RUN_CANCEL_ID.set(body.cancel_id)
cancel = threading.Event()
+ # A chat tools call that is stopped stops this run too.
+ bind_generation_cancel(cancel)
event_token = _AUDIO_RUN_CANCEL.set(cancel)
created: list[str] = []
created_token = _AUDIO_RUN_CREATED.set(created)
@@ -24485,6 +24689,8 @@ async def _run_separation(
claim_resident = False,
require_audio_workflow = "separate",
)
+ if not body.model:
+ await _route_to_kept_audio_model("separate")
backend = await asyncio.to_thread(get_inference_backend)
model_info = (
backend.models.get(backend.active_model_name, {}) if backend.active_model_name else {}
@@ -31352,13 +31558,12 @@ async def produce_openai_chat_completions(
else:
backend = await asyncio.to_thread(get_inference_backend)
if not backend.active_model_name:
- _status, _detail = await _no_model_loaded_error(
+ await _raise_no_model_loaded(
"No model loaded. Call POST /inference/load first.",
_switch_model_for_payload(payload),
request,
status = 400,
)
- raise HTTPException(status_code = _status, detail = _detail)
# Public id so the response never echoes a local path.
model_name = _orchestrator_public_model_id(backend) or payload.model
model_info = backend.models.get(backend.active_model_name, {})
@@ -37940,13 +38145,12 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
else _active_managed_engine_backend()
)
if not llama_backend.is_loaded and mlx_backend is None and engine_backend is None:
- _status, _detail = await _no_model_loaded_error(
+ await _raise_no_model_loaded(
"No GGUF model loaded. Load a GGUF model first.",
_raw_body_model(body),
request,
status = 503,
)
- raise HTTPException(status_code = _status, detail = _detail)
if not isinstance(body, dict):
# Re-read to re-raise a malformed-body error; a valid non-dict body gets a clean 400.
body = await request.json()
@@ -38724,13 +38928,12 @@ async def openai_embeddings(request: Request, current_subject: str = Depends(get
else:
_decisive = False
if _decisive or not isinstance(body, dict):
- _status, _detail = await _no_model_loaded_error(
+ await _raise_no_model_loaded(
"No GGUF model loaded. Load a GGUF model first.",
_named,
request,
status = 503,
)
- raise HTTPException(status_code = _status, detail = _detail)
if not isinstance(body, dict):
# Re-read to re-raise a malformed-body error; a valid non-dict body gets a clean 400.
body = await request.json()
@@ -42507,6 +42710,7 @@ async def chat_count_tokens(
raise HTTPException(
status_code = 503,
detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+ headers = problem_headers("not_loaded", kind = "llm"),
)
# Route FIRST: the passthrough does not merge adjacent user turns, so coalescing would misprice.
@@ -43296,13 +43500,12 @@ async def anthropic_count_tokens(
)
if _in_process_count is not None:
return _in_process_count
- _status, _detail = await _no_model_loaded_error(
+ await _raise_no_model_loaded(
"No GGUF model loaded. Load a GGUF model first.",
_switch_model_for_payload(payload),
request,
status = 503,
)
- raise HTTPException(status_code = _status, detail = _detail)
# system is folded into the messages list, so pass system=None to the counter.
openai_messages = anthropic_messages_to_openai(
@@ -43918,6 +44121,7 @@ async def anthropic_messages(
raise HTTPException(
status_code = 503,
detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+ headers = problem_headers("not_loaded", kind = "llm"),
)
# max_tokens is required by Anthropic; validate before auto-switch so no load is triggered.
@@ -44062,13 +44266,12 @@ async def anthropic_messages(
website_policy = website_policy,
)
if not llama_backend.is_loaded:
- _status, _detail = await _no_model_loaded_error(
+ await _raise_no_model_loaded(
"No GGUF model loaded. Load a GGUF model first.",
_switch_model_for_payload(payload),
request,
status = 503,
)
- raise HTTPException(status_code = _status, detail = _detail)
# Repo id after an auto-switch, else a clean public id; never a local .gguf path or raw payload path.
model_name = _llama_public_model_id(llama_backend, payload.model)
@@ -49858,7 +50061,13 @@ async def _generate_diffusion_image_run(
except RuntimeError as exc:
# Match these two EXACT client-state messages (409); other RuntimeErrors are failures.
msg = str(exc)
- if msg in (DIFFUSION_NOT_LOADED_MSG, DIFFUSION_CANCELLED_MSG):
+ if msg == DIFFUSION_NOT_LOADED_MSG:
+ raise HTTPException(
+ status_code = 409,
+ detail = msg,
+ headers = problem_headers("not_loaded", kind = "image"),
+ )
+ if msg == DIFFUSION_CANCELLED_MSG:
raise HTTPException(status_code = 409, detail = msg)
refusal = unified_memory_refusal_code(exc)
if refusal is not None:
@@ -52062,7 +52271,11 @@ async def _generate_openai_images(
status = backend.status()
if not status.get("loaded"):
# Mirror /v1/completions and /v1/embeddings, which 503 when their backend is not loaded.
- raise HTTPException(status_code = 503, detail = _NO_IMAGE_MODEL_MSG)
+ raise HTTPException(
+ status_code = 503,
+ detail = _NO_IMAGE_MODEL_MSG,
+ headers = problem_headers("not_loaded", kind = "image"),
+ )
if account_access.managed_account():
await asyncio.to_thread(
@@ -52122,7 +52335,11 @@ async def _generate_openai_images(
except Exception as exc: # noqa: BLE001 (single boundary, sanitized envelope)
# A RuntimeError with the model now unloaded means it was evicted mid-call (a race): 503. Every other failure is a real 500 whose raw message must not reach the client.
if isinstance(exc, RuntimeError) and not backend.is_loaded:
- raise HTTPException(status_code = 503, detail = _NO_IMAGE_MODEL_MSG)
+ raise HTTPException(
+ status_code = 503,
+ detail = _NO_IMAGE_MODEL_MSG,
+ headers = problem_headers("not_loaded", kind = "image"),
+ )
# Typed: the activation refusal is written for the caller; no other ValueError text escapes.
if isinstance(exc, ImageActivationShortfallError):
raise HTTPException(
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 47837161f7b..6fa4ed1a6b0 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -30,6 +30,7 @@ from core.inference.mcp_client import (
close_mcp_sessions,
invalidate_tool_cache,
is_stdio,
+ is_studio_tools,
join_stdio_command,
list_tools_async,
oauth_client_kwargs,
@@ -207,6 +208,16 @@ def _blender_row():
)
+def _require_ui_for_studio_tools(via_api_key, no_credential = False) -> None:
+ # The row runs Unsloth Studio's own tools as the account, so like a stdio command only a UI session adds it.
+ if via_api_key or no_credential:
+ raise HTTPException(
+ status_code = 403,
+ detail = "The Unsloth Studio tools server can only be added from the Unsloth Studio UI, "
+ "not with an API key.",
+ )
+
+
def _require_managed_access(
via_api_key,
no_credential,
@@ -367,6 +378,7 @@ async def create_mcp_server(
payload: McpServerCreate,
current_subject: str = Depends(get_current_subject),
via_api_key: ViaApiKey = False,
+ no_credential: WithoutCredential = False,
):
display_name = (payload.display_name or "").strip()
if not display_name:
@@ -374,6 +386,8 @@ async def create_mcp_server(
url = _validate_url(payload.url)
if is_stdio(url):
require_ui_session_for_local_commands(via_api_key)
+ if is_studio_tools(url):
+ _require_ui_for_studio_tools(via_api_key, no_credential)
headers = _normalize_headers(payload.headers)
# OAuth is HTTP-only; a stale flag would push stdio probes onto the 305s OAuth timeout.
use_oauth = payload.use_oauth and not is_stdio(url)
@@ -470,6 +484,9 @@ async def update_mcp_server(
# Check both directions before any side effect; API keys must not repoint http rows or edit stdio env
if is_stdio(old["url"]) or is_stdio(changes.get("url", old["url"])):
require_ui_session_for_local_commands(via_api_key)
+ # Repointing either way; plain edits such as is_enabled stay open to API keys, as for any http row.
+ if "url" in changes and (is_studio_tools(old["url"]) or is_studio_tools(changes["url"])):
+ _require_ui_for_studio_tools(via_api_key, no_credential)
# On transport switch with no new headers, drop old ones so env secrets are not sent as HTTP headers
if (
"url" in changes
@@ -612,6 +629,7 @@ async def import_mcp_servers(
payload: McpServerImportRequest,
current_subject: str = Depends(get_current_subject),
via_api_key: ViaApiKey = False,
+ no_credential: WithoutCredential = False,
):
"""Bulk-register servers from a standard mcpServers JSON config (issue
#5936). Each entry rides the existing create path: _validate_url applies
@@ -630,6 +648,8 @@ async def import_mcp_servers(
# Checked per entry: an API-key import of a mixed config still creates http entries, reports stdio.
if is_stdio(url):
require_ui_session_for_local_commands(via_api_key)
+ if is_studio_tools(url):
+ _require_ui_for_studio_tools(via_api_key, no_credential)
headers = _normalize_headers(entry.headers)
except HTTPException as exc:
errors.append(f"{entry.display_name}: {exc.detail}")
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 4ed7c8fc6da..a67db551463 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -4196,6 +4196,7 @@ class McpToolSetting(BaseModel):
name: str
area: str
enabled: bool
+ chat: bool
class McpAccessResponse(BaseModel):
@@ -4695,14 +4696,20 @@ def _require_ui_session_for_mcp(via_api_key: bool = Depends(authenticated_via_ap
def _mcp_access_response(request: Request) -> McpAccessResponse:
- from mcp_server import tool_catalog
+ from mcp_server import tool_catalog, withheld
+
+ from_chat = withheld()
record = mcp_owner_record()
tools = None
if record is not None:
disabled = record[1]
tools = [
- McpToolSetting(**entry, enabled = disabled is not None and entry["name"] not in disabled)
+ McpToolSetting(
+ **entry,
+ enabled = disabled is not None and entry["name"] not in disabled,
+ chat = entry["name"] not in from_chat,
+ )
for entry in tool_catalog()
]
return McpAccessResponse(
diff --git a/studio/backend/routes/video.py b/studio/backend/routes/video.py
index 101145087c0..60e41f42107 100644
--- a/studio/backend/routes/video.py
+++ b/studio/backend/routes/video.py
@@ -80,7 +80,7 @@ from models.inference import (
VideoUnloadResponse,
)
from utils.account_context import current_account_id, is_owner_context
-from utils.api_errors import openai_error_body
+from utils.api_errors import openai_error_body, problem_headers
from utils.upload_limits import VIDEO_INPUT_REFERENCE_MAX_BYTES
logger = get_logger(__name__)
@@ -820,11 +820,13 @@ async def generate_video(
msg = str(exc)
if msg == VIDEO_MODEL_CHANGED_MSG and attempt == 0:
continue
- if msg in (
- VIDEO_NOT_LOADED_MSG,
- VIDEO_GENERATION_BUSY_MSG,
- VIDEO_MODEL_CHANGED_MSG,
- ):
+ if msg == VIDEO_NOT_LOADED_MSG:
+ raise HTTPException(
+ status_code = 409,
+ detail = msg,
+ headers = problem_headers("not_loaded", kind = "video"),
+ )
+ if msg in (VIDEO_GENERATION_BUSY_MSG, VIDEO_MODEL_CHANGED_MSG):
raise HTTPException(status_code = 409, detail = msg)
logger.error("video.generate_failed: %s", exc, exc_info = True)
raise HTTPException(status_code = 500, detail = video_failure_detail(exc))
@@ -2353,7 +2355,11 @@ async def _start_openai_video(
else:
status = await asyncio.to_thread(backend.status)
if not status.get("loaded"):
- raise HTTPException(status_code = 503, detail = _NO_VIDEO_MODEL_MSG)
+ raise HTTPException(
+ status_code = 503,
+ detail = _NO_VIDEO_MODEL_MSG,
+ headers = problem_headers("not_loaded", kind = "video"),
+ )
if account_access.managed_account():
await asyncio.to_thread(account_access.require_media_generation_access, status, "video")
defaults = status.get("defaults") or {}
@@ -2402,7 +2408,11 @@ async def _start_openai_video(
except RuntimeError as exc:
msg = str(exc)
if msg == VIDEO_NOT_LOADED_MSG:
- raise HTTPException(status_code = 503, detail = _NO_VIDEO_MODEL_MSG)
+ raise HTTPException(
+ status_code = 503,
+ detail = _NO_VIDEO_MODEL_MSG,
+ headers = problem_headers("not_loaded", kind = "video"),
+ )
if msg == VIDEO_GENERATION_BUSY_MSG:
raise _openai_video_error(409, msg)
if msg == VIDEO_MODEL_CHANGED_MSG:
diff --git a/studio/backend/studio_mcp/audio_runs.py b/studio/backend/studio_mcp/audio_runs.py
new file mode 100644
index 00000000000..b4d91eb58c3
--- /dev/null
+++ b/studio/backend/studio_mcp/audio_runs.py
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""generate_audio runs in flight, so a cancel can stop a run between its takes."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class _Run:
+ cancelled: bool = False
+ in_flight: bool = False
+
+
+# generate_audio runs by (account, cancel_id), and ids cancelled lately; the route keeps an early
+# cancel as long, so a reused id would be stopped on arrival.
+_RUNS: dict[tuple[str, str], _Run] = {}
+_CANCELLED: dict[tuple[str, str], float] = {}
+CANCEL_MEMORY_S = 30.0
+
+
+def _forget_old_cancels() -> None:
+ cutoff = time.monotonic() - CANCEL_MEMORY_S
+ for key in [key for key, at in _CANCELLED.items() if at < cutoff]:
+ del _CANCELLED[key]
+
+
+def stop_run(account: str, cancel_id: str) -> Optional[bool]:
+ """Mark run ``cancel_id`` cancelled: None when no generate_audio run here has that id, True when it stops between takes, False when a take is running and the route must stop it."""
+ _forget_old_cancels()
+ _CANCELLED[(account, cancel_id)] = time.monotonic()
+ run = _RUNS.get((account, cancel_id))
+ if run is None:
+ return None
+ run.cancelled = True
+ return not run.in_flight
diff --git a/studio/backend/studio_mcp/caller.py b/studio/backend/studio_mcp/caller.py
index 429255abed3..217f3f9d80d 100644
--- a/studio/backend/studio_mcp/caller.py
+++ b/studio/backend/studio_mcp/caller.py
@@ -1,13 +1,16 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Who is calling an MCP tool. The gate validates the key and records the caller in the request scope; tools read it back here, because fastmcp's own header accessor drops ``Authorization``."""
+"""Who is calling an MCP tool. The gate validates the key and records the caller in the request scope; tools read it back here, because fastmcp's own header accessor drops ``Authorization``. The chat's in-process bridge has no HTTP request, so it binds its caller in a ContextVar instead."""
from __future__ import annotations
+from contextvars import ContextVar, Token
from dataclasses import dataclass, field
from typing import Any, Optional
+from studio_mcp.profile import AGENT, CallerProfile
+
STATE_KEY = "unsloth_mcp"
@@ -22,6 +25,16 @@ class Caller:
# The outer Studio app, so forwarded calls never need to import main.
studio_app: Any = field(repr = False)
hf_token: Optional[str] = field(default = None, repr = False)
+ # Who the call answers to: an agent on /mcp, or a chat turn through the bridge.
+ profile: CallerProfile = AGENT
+
+ @property
+ def call_scoped(self) -> bool:
+ return self.profile.call_scoped
+
+ @property
+ def reads_host_files(self) -> bool:
+ return self.direct_local and self.profile.host_files
def caller_from_scope(scope: dict) -> Optional[Caller]:
@@ -29,10 +42,27 @@ def caller_from_scope(scope: dict) -> Optional[Caller]:
return caller if isinstance(caller, Caller) else None
+_bound: ContextVar[Optional[Caller]] = ContextVar("unsloth_mcp_bound_caller", default = None)
+
+
+def bind_caller(caller: Caller) -> Token:
+ return _bound.set(caller)
+
+
+def reset_caller(token: Token) -> None:
+ _bound.reset(token)
+
+
def current_caller() -> Caller:
from fastmcp.server.dependencies import get_http_request
- caller = caller_from_scope(get_http_request().scope)
+ try:
+ request = get_http_request()
+ except RuntimeError:
+ caller = _bound.get()
+ else:
+ # An HTTP request always answers for itself, so /mcp never sees a bound caller.
+ caller = caller_from_scope(request.scope)
if caller is None:
raise RuntimeError("Unsloth Studio MCP tools need a caller admitted by the /mcp gate.")
return caller
diff --git a/studio/backend/studio_mcp/errors.py b/studio/backend/studio_mcp/errors.py
index 12a57cefef6..89ef4e36fdb 100644
--- a/studio/backend/studio_mcp/errors.py
+++ b/studio/backend/studio_mcp/errors.py
@@ -13,6 +13,7 @@ import httpx
from fastmcp.exceptions import ToolError
from hub.utils.host_paths import redact_paths_in_text
+from studio_mcp import problems
from studio_mcp.forward import parse_json
# Route errors sometimes tell a browser client which route to call next ("Call POST /inference/load
@@ -38,40 +39,11 @@ _DEFERRED_ERROR_KEY = "_deferred_error"
REFUSAL_HEADER = "x-unsloth-refusal"
MEMORY_REFUSAL = "memory-estimate"
MULTI_MODEL_REFUSAL = "multi-model-always"
-# Copy the Keep multiple models loaded refusal uses when no header or code came with it.
-MULTI_MODEL_MARKERS = ("is set to Always", "is set to keep loaded")
_TAG_CODE = re.compile(r"^[a-z][a-z0-9_]{1,63}$")
_TAG_VALUE = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
-UNLOAD_KINDS = {"chat": "llm", "audio": "audio", "image": "image", "video": "video"}
-MULTI_MODEL_HINT = "Call unload_model(kind='{kind}') to free the GPU; retrying won't help."
-MULTI_MODEL_HINT_ANY = (
- "Call unload_model(kind=…) for the model it names to free the GPU; retrying won't help."
-)
-ACTIVE_GENERATIONS_HINT = (
- "Wait for the running chats to finish, or cancel a chat you started with"
- " cancel(kind='chat', id=<its cancel_id>)."
-)
MEMORY_HINT = "Pass allow_oversized=true to try anyway."
-# Guidance for a route's own error code, used in place of the tool's status hint.
-CODE_HINTS: dict[str, str] = {}
-
-_UNLOAD_KIND = re.compile(r"would unload the (\w+) model")
-_NOT_LOADED = re.compile(r"^No (?:(diffusion|image|video|GGUF) )?model (?:is )?loaded")
-# The kind a "No <word> model loaded" names outright, whatever route said it.
-_NOT_LOADED_WORDS = {"diffusion": "image", "image": "image", "video": "video", "GGUF": "chat"}
-# The kind a bare "No model loaded" is about, by the route that said it. First match wins.
-_NOT_LOADED_PATHS = (
- ("/v1/audio/transcriptions", "stt"),
- ("/api/inference/audio/stt/", "stt"),
- ("/v1/audio/", "audio"),
- ("/api/inference/audio/", "audio"),
- ("/v1/images/", "image"),
- ("/api/inference/images/", "image"),
- ("/v1/videos", "video"),
- ("/api/inference/video/", "video"),
-)
# llama-server's startup output, as core/inference/llama_cpp.py _with_startup_diagnostics frames it.
_LLAMA_OUTPUT = "\n\nllama-server output:\n"
@@ -177,22 +149,14 @@ def _refusal(headers: Mapping[str, str]) -> str:
return str(headers.get(REFUSAL_HEADER) or "").strip().lower()
-def _not_loaded_kind(message: str, path: str) -> Optional[str]:
- match = _NOT_LOADED.match(message.strip())
- if match is None:
- return None
- if match.group(1):
- return _NOT_LOADED_WORDS[match.group(1)]
- return next((kind for prefix, kind in _NOT_LOADED_PATHS if path.startswith(prefix)), "chat")
-
-
def _describe(
status: int,
body: Any,
headers: Mapping[str, str],
- path: str = "",
+ tools: Optional[frozenset[str]] = None,
) -> tuple[Optional[str], str, Optional[str]]:
- """(tag, message, own hint). An own hint replaces the tool's status hint."""
+ """(tag, message, own hint). An own hint replaces the tool's status hint. ``tools`` are the
+ caller's, so a hint names only tools it has; None reads them from the current caller."""
# Scrubbed before the hints go on: the redactor drops everything after a path it finds.
retry_after = headers.get("retry-after")
busy = _gpu_busy(body)
@@ -230,37 +194,37 @@ def _describe(
message = _brief(message)
scrubbed = _scrub(message)
suffix = f"{scrubbed} (HTTP {status})"
-
- if (
- _refusal(headers) == MULTI_MODEL_REFUSAL
- or code == "multi_model_always"
- or (status == 409 and any(marker in message for marker in MULTI_MODEL_MARKERS))
+ problem = problems.from_headers(headers)
+ if problem is None and (
+ _refusal(headers) == MULTI_MODEL_REFUSAL or code == "multi_model_always"
):
- # Retrying cannot help: the setting keeps the other model loaded until it is unloaded.
found = detail.get("kind") if isinstance(detail, dict) else None
- if not isinstance(found, str):
- match = _UNLOAD_KIND.search(message)
- found = match.group(1) if match else None
- kind = UNLOAD_KINDS.get(found or "")
- if kind is None:
- return _tag("multi_model_always"), suffix, MULTI_MODEL_HINT_ANY
- return _tag("multi_model_always", kind = found), suffix, MULTI_MODEL_HINT.format(kind = kind)
-
- if isinstance(detail, dict) and "active_generations" in (detail.get("error"), code):
- # The route's thread_ids are browser conversation ids; an agent can only cancel its own chats.
- tag = _tag("active_generations", running = detail.get("running"))
- return tag, suffix, ACTIVE_GENERATIONS_HINT
-
- if status == 400 and _refusal(headers) == MEMORY_REFUSAL:
+ problem = problems.Problem(
+ "multi_model_always", {"kind": found} if isinstance(found, str) else {}
+ )
+ if (
+ problem is None
+ and isinstance(detail, dict)
+ and "active_generations" in (detail.get("error"), code)
+ ):
+ # The route's thread_ids are browser conversation ids; an agent cancels only its own chats.
+ problem = problems.Problem("active_generations", {"running": detail.get("running")})
+ if problem is None and status == 400 and _refusal(headers) == MEMORY_REFUSAL:
return _tag("memory_estimate"), f"{scrubbed} {MEMORY_HINT}", None
-
- tag = _tag(code)
- if tag is None:
- kind = _not_loaded_kind(message, path)
- tag = _tag("not_loaded", kind = kind) if kind else None
- if status == 503 and retry_after:
+ if problem is None:
+ if status == 503 and retry_after:
+ suffix += f" Retry after {retry_after} s."
+ return _tag(code), suffix, None
+ # Retrying a multi_model_always refusal cannot help, so it never gets the 503 retry line.
+ if status == 503 and retry_after and problem.code != "multi_model_always":
suffix += f" Retry after {retry_after} s."
- return tag, suffix, CODE_HINTS.get(code) if isinstance(code, str) else None
+ fields = (
+ {"running": problem.fields.get("running")}
+ if problem.code == "active_generations"
+ else problem.tag_fields()
+ )
+ hint = problems.hint(problem, problems.caller_tools() if tools is None else tools)
+ return _tag(problem.code, **fields), suffix, hint
def _body(resp: httpx.Response) -> Any:
@@ -270,16 +234,8 @@ def _body(resp: httpx.Response) -> Any:
return resp.text.strip()
-def _request_path(resp: httpx.Response) -> str:
- # A Response built by hand (tests) has no request, and .request raises then.
- try:
- return resp.request.url.path
- except RuntimeError:
- return ""
-
-
-def raise_for_payload(payload: Any, *, path: str = "") -> Any:
- """Raise for an error carried inside a successful response; return the payload otherwise. ``path`` is the route that answered, for the tag's kind."""
+def raise_for_payload(payload: Any) -> Any:
+ """Raise for an error carried inside a successful response; return the payload otherwise."""
if isinstance(payload, dict):
deferred = payload.get(_DEFERRED_ERROR_KEY)
if deferred is not None:
@@ -291,9 +247,7 @@ def raise_for_payload(payload: Any, *, path: str = "") -> Any:
sent = deferred.get("headers")
sent = sent if isinstance(sent, dict) else {}
headers = {str(key).lower(): str(value) for key, value in sent.items()}
- tag, message, hint = _describe(
- status, {"detail": deferred.get("detail")}, headers, path
- )
+ tag, message, hint = _describe(status, {"detail": deferred.get("detail")}, headers)
raise tool_error(message, hint, tag = tag)
if payload.get("type") == "error":
nested = payload.get("error")
@@ -318,9 +272,8 @@ def raise_for_route(
hints: Optional[Mapping[int, str]] = None,
) -> Any:
"""Raise a ToolError when the forwarded call failed; otherwise return its parsed JSON (or ``payload`` when the caller already parsed it, e.g. the last NDJSON line). ``hints`` maps a status to what the agent should do about it; an answer with its own guidance (gpu_busy, Keep multiple models loaded, running chats) keeps that instead."""
- path = _request_path(resp)
if resp.status_code >= 400:
- tag, message, own = _describe(resp.status_code, _body(resp), resp.headers, path)
+ tag, message, own = _describe(resp.status_code, _body(resp), resp.headers)
hint = own if own is not None else (hints or {}).get(resp.status_code)
raise tool_error(message, hint or None, tag = tag)
if payload is None:
@@ -328,31 +281,16 @@ def raise_for_route(
payload = parse_json(resp.content) if resp.content.strip() else None
except (ValueError, UnicodeDecodeError):
return None
- return raise_for_payload(payload, path = path)
+ return raise_for_payload(payload)
# Audio failures carry a code (detail.code on /api, error.code on /v1); each gets what to do next.
-_UPDATE_AUDIO_RUNTIME = (
- "Update the audio runtime (`unsloth studio update`), then load the model again."
-)
-AUDIO_HINTS = {
- "out_of_memory": "Load the audio model again with device='cpu'{variants}.",
- "gpu_unavailable": "Load the audio model again with device='cpu'.",
- "runtime_missing": _UPDATE_AUDIO_RUNTIME,
- "family_unknown_to_runtime": _UPDATE_AUDIO_RUNTIME,
- "espeak_missing": _UPDATE_AUDIO_RUNTIME,
- "runtime_stopped": "Retry once; if it fails again, run studio_status and load_model the audio "
- "model again.",
- "file_incomplete": "Download the model again, or load another variant.",
-}
-
-
def _audio_failure(body: Any) -> Optional[dict]:
if not isinstance(body, dict):
return None
for holder in (body.get("detail"), body.get("error")):
if isinstance(holder, dict) and isinstance(holder.get("code"), str):
- return holder if holder["code"] in AUDIO_HINTS else None
+ return holder if holder["code"] in problems.AUDIO_CODES else None
return None
@@ -362,7 +300,7 @@ def audio_code(body: Any) -> Optional[str]:
return failure["code"] if failure is not None else None
-def audio_hint(body: Any) -> Optional[str]:
+def audio_hint(body: Any, tools: Optional[frozenset[str]] = None) -> Optional[str]:
failure = _audio_failure(body)
if failure is None:
return None
@@ -371,10 +309,8 @@ def audio_hint(body: Any) -> Optional[str]:
name = row.get("variant") if isinstance(row, dict) else row
if isinstance(name, str) and name:
names.append(name)
- variants = (
- f", or a smaller variant with load_model(variant=...): {', '.join(names)}" if names else ""
- )
- return AUDIO_HINTS[failure["code"]].format(variants = variants)
+ tools = problems.caller_tools() if tools is None else tools
+ return problems.audio_hint(failure["code"], names, tools)
def raise_for_audio(resp: httpx.Response, *, hints: Optional[Mapping[int, str]] = None) -> Any:
diff --git a/studio/backend/studio_mcp/inputs.py b/studio/backend/studio_mcp/inputs.py
index 782599f32b2..a7f9c78d54d 100644
--- a/studio/backend/studio_mcp/inputs.py
+++ b/studio/backend/studio_mcp/inputs.py
@@ -64,7 +64,7 @@ def sniff_image(data: bytes) -> Optional[str]:
def read_local(caller: Caller, path: str, max_bytes: int) -> bytes:
"""A file named by the agent, read only for a caller on this computer and only when within ``max_bytes``."""
- if not caller.direct_local:
+ if not caller.reads_host_files:
raise ToolError(PATH_REMOTE)
file = Path(path).expanduser()
try:
diff --git a/studio/backend/studio_mcp/job_kinds.py b/studio/backend/studio_mcp/job_kinds.py
new file mode 100644
index 00000000000..8cc1039f982
--- /dev/null
+++ b/studio/backend/studio_mcp/job_kinds.py
@@ -0,0 +1,540 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The kinds of work get_job reads and cancel stops, each registered with studio_mcp.jobs: how to read its state and how to stop it."""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any, Callable, Optional
+from urllib.parse import quote
+
+from fastmcp.exceptions import ToolError
+from fastmcp.tools import ToolResult
+
+from studio_mcp import audio_runs, export_jobs, job_store, loading, model_downloads, video_queue
+from studio_mcp import checkpoints as named
+from studio_mcp.caller import Caller
+from studio_mcp.errors import raise_for_route
+from studio_mcp.forward import forward
+from studio_mcp.jobs import Cancel, Kind, Stop, register
+from studio_mcp.media import (
+ INLINE_CAP,
+ THUMB_SIDE,
+ ReturnMedia,
+ image_content,
+ media_result,
+ public_url,
+ resource_link,
+ signed_url,
+ video_frame_path,
+)
+from studio_mcp.outputs import (
+ ExportInfo,
+ ExportJobSummary,
+ JobStatus,
+ JobSummary,
+ RecipeInfo,
+ TrainingJob,
+ VideoInfo,
+)
+from studio_mcp.tools import EXPORT_STATUS, as_dict, integer, leaf_name, number, opt_text
+from studio_mcp.tools import route_json
+from studio_mcp.tools.status import SLOT_ROUTES, _diffusion_training, _training
+
+
+def _message(answer: Any) -> Optional[str]:
+ if isinstance(answer, dict):
+ return opt_text(answer.get("message")) or opt_text(answer.get("status"))
+ return None
+
+
+def _outcome(answer: Any, stopped: Callable[[dict], Any], job_id: Optional[str]) -> Stop:
+ """Each route answers an idle cancel normally, so success alone means nothing: ``stopped`` reads whether it stopped something."""
+ return Stop(isinstance(answer, dict) and bool(stopped(answer)), _message(answer), job_id)
+
+
+def _route_cancel(path: str, id_field: Optional[str], stopped: Callable[[dict], Any]) -> Cancel:
+ """A cancel that posts to ``path``, with the id (or ``save``) in body field ``id_field`` if any."""
+
+ async def cancel(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ answer = await route_json(
+ "POST",
+ path.format(id = quote(job_id or "", safe = "")),
+ caller = caller,
+ **(
+ {"json_body": {id_field: save if id_field == "save" else job_id}}
+ if id_field
+ else {}
+ ),
+ )
+ return _outcome(answer, stopped, job_id)
+
+ return cancel
+
+
+def _cancelled(answer: dict) -> Any:
+ return answer.get("cancelled")
+
+
+# "cancelled" here is a job that had already ended; only "cancelling" means this call stopped it.
+def _cancelling(answer: dict) -> bool:
+ return answer.get("state") == "cancelling"
+
+
+def _recipe_cancelling(answer: dict) -> bool:
+ return answer.get("status") == "cancelling"
+
+
+def _video_path(video_id: str, suffix: str = "") -> str:
+ return f"/v1/videos/{quote(video_id, safe = '')}{suffix}"
+
+
+async def _video_job(
+ caller: Caller,
+ video_id: str,
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
+) -> ToolResult:
+ job = as_dict(await route_json("GET", _video_path(video_id), caller = caller))
+ error = as_dict(job.get("error"))
+ contents: list[Any] = []
+ video = None
+ if job.get("status") == "completed":
+ # A picture at most: the MP4 can be hundreds of MB and is shared as a link.
+ video_url = public_url(caller, _video_path(video_id, "/content"))
+ download_url = await signed_url(caller, "video", video_id)
+ thumb, mime = None, "image/webp"
+ if return_media == "inline":
+ thumb = await forward(
+ caller, "GET", _video_path(video_id, "/content"), params = {"variant": "thumbnail"}
+ )
+ elif return_media == "preview":
+ params = {"at": "first", "max_px": preview_px or THUMB_SIDE}
+ thumb = await forward(caller, "GET", video_frame_path(video_id), params = params)
+ mime = "image/png"
+ inline = thumb is not None and thumb.status_code == 200 and len(thumb.content) <= INLINE_CAP
+ if inline:
+ contents.append(image_content(thumb.content, mime))
+ contents.append(resource_link(download_url or video_url, f"{video_id}.mp4", "video/mp4"))
+ video = VideoInfo(url = video_url, download_url = download_url, thumbnail_inline = inline)
+ status = JobStatus(
+ kind = "video",
+ id = opt_text(job.get("id")) or video_id,
+ status = "cancelled" if error.get("code") == "cancelled" else opt_text(job.get("status")),
+ progress_percent = number(job.get("progress")),
+ error = opt_text(error.get("message")),
+ error_code = opt_text(error.get("code")),
+ video = video,
+ seed = integer(job.get("seed")),
+ )
+ return media_result(contents, status)
+
+
+async def _video_jobs(caller: Caller) -> ToolResult:
+ listing = await route_json("GET", "/v1/videos", caller = caller)
+ rows = as_dict(listing).get("data")
+ jobs = [
+ JobSummary.from_route(
+ row,
+ status = (
+ "cancelled"
+ if as_dict(row.get("error")).get("code") == "cancelled"
+ else opt_text(row.get("status")) or "queued"
+ ),
+ progress_percent = number(row.get("progress")),
+ )
+ for row in rows or []
+ if isinstance(row, dict) and opt_text(row.get("id"))
+ ]
+ return media_result([], JobStatus(kind = "video", jobs = jobs))
+
+
+async def _read_video(
+ caller: Caller,
+ job_id: Optional[str],
+ *,
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
+ **_unused: Any,
+) -> ToolResult:
+ if job_id is None:
+ return await _video_jobs(caller)
+ if video_queue.is_queue_id(job_id):
+ item = video_queue.lookup(caller.account_id, job_id)
+ if not item.video_id:
+ queued = await video_queue.job_status(item)
+ # Unless it started while that was read: then it is the video it became.
+ if not item.video_id:
+ return media_result([], queued)
+ return await _video_job(caller, item.video_id, return_media, preview_px)
+ return await _video_job(caller, job_id, return_media, preview_px)
+
+
+_cancel_rendering = _route_cancel("/api/inference/video/generate/cancel", "video_id", _cancelled)
+
+
+async def _cancel_video(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ if job_id and video_queue.is_queue_id(job_id):
+ return Stop(*video_queue.cancel(caller.account_id, job_id), job_id)
+ return await _cancel_rendering(caller, job_id, save)
+
+
+RECIPE_ROUTES = "/api/data-recipe"
+
+
+def _recipe_dataset(artifact_path: Any) -> Optional[str]:
+ leaf = leaf_name(artifact_path) if opt_text(artifact_path) else None
+ return f"recipes/{leaf}" if leaf else None
+
+
+async def _read_recipe(
+ caller: Caller,
+ job_id: Optional[str],
+ *,
+ rows: Optional[int] = None,
+ offset: int = 0,
+ **_unused: Any,
+) -> ToolResult:
+ path = (
+ f"{RECIPE_ROUTES}/jobs/{quote(job_id, safe = '')}/status"
+ if job_id
+ else f"{RECIPE_ROUTES}/jobs/current"
+ )
+ if job_id:
+ job = await route_json("GET", path, caller = caller)
+ else:
+ response = await forward(caller, "GET", path)
+ # No recipe has run since Unsloth Studio started: nothing to report, not an error.
+ if response.status_code == 404:
+ return media_result([], JobStatus(kind = "recipe", jobs = []))
+ job = raise_for_route(response)
+ job = as_dict(job)
+ job_id = opt_text(job.get("job_id")) or job_id
+ progress = as_dict(job.get("progress"))
+ data_rows = total = None
+ if rows and job_id:
+ response = await forward(
+ caller,
+ "GET",
+ f"{RECIPE_ROUTES}/jobs/{quote(job_id, safe = '')}/dataset",
+ params = {"limit": rows, "offset": offset},
+ )
+ # 404 while no rows are written yet, 422 when the job ended without any (its detail names host
+ # paths): the status still answers, without rows.
+ page = None if response.status_code in (404, 422) else raise_for_route(response)
+ if isinstance(page, dict):
+ data_rows = [row for row in page.get("dataset") or [] if isinstance(row, dict)]
+ total = integer(page.get("total"))
+ status = JobStatus.from_route(
+ job,
+ kind = "recipe",
+ id = job_id,
+ progress_percent = number(progress.get("percent")),
+ recipe = RecipeInfo.from_route(
+ job,
+ dataset = _recipe_dataset(job.get("artifact_path")),
+ total_rows = total,
+ data_rows = data_rows,
+ ),
+ )
+ return media_result([], status)
+
+
+def _export_status(job: export_jobs.ExportJob) -> JobStatus:
+ return JobStatus(
+ kind = "export",
+ id = job.job_id,
+ status = job.status,
+ error = job.error,
+ export = ExportInfo(format = job.format, output = job.output, phase = job.phase),
+ )
+
+
+async def _read_export(caller: Caller, job_id: Optional[str], **_unused: Any) -> ToolResult:
+ if job_id is None:
+ jobs = [
+ ExportJobSummary(
+ id = job.job_id,
+ status = job.status,
+ format = job.format,
+ phase = job.phase,
+ output = job.output,
+ error = job.error,
+ )
+ for job in reversed(export_jobs.jobs_of(caller.account_id))
+ ]
+ return media_result([], JobStatus(kind = "export", jobs = jobs))
+ # Settles from its own export call, not the export status (that is whichever op ran last).
+ return media_result([], _export_status(export_jobs.lookup(caller.account_id, job_id)))
+
+
+# How long a cancel waits for a job whose export just finished to record its own result.
+SETTLE_S = 2.0
+EXPORT_STOPPED = "The export was stopped and its checkpoint unloaded."
+
+
+def _export_stopped(answer: dict) -> bool:
+ return answer.get("message") == "Export cancelled"
+
+
+async def _cancel_export_job(caller: Any, job: export_jobs.ExportJob) -> tuple[bool, str]:
+ """Stop only this job's own step: the route stops the worker when that op runs and otherwise refuses it when it starts."""
+ for _ in range(3):
+ op_id = job.op_id
+ if op_id is None:
+ break
+ answer = await route_json(
+ "POST", "/api/export/cancel", caller = caller, json_body = {"expected_op_id": op_id}
+ )
+ if isinstance(answer, dict) and _export_stopped(answer):
+ job_store.mark_cancelled(job)
+ return True, EXPORT_STOPPED
+ # Its step just ended, or is queued behind someone else's: let a finished job report itself.
+ await job_store.settle(job, SETTLE_S)
+ if job.finished:
+ return False, f"The export already {job.status}."
+ if job.op_id == op_id:
+ break
+ job_store.mark_cancelled(job)
+ return True, "The export job was stopped before its next step."
+
+
+async def _cancel_export(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ if job_id:
+ job = export_jobs.lookup(caller.account_id, job_id)
+ if job.finished:
+ return Stop(False, f"The export already {job.status}.", job_id)
+ return Stop(*await _cancel_export_job(caller, job), job_id)
+ status = await route_json("GET", EXPORT_STATUS, caller = caller)
+ if not as_dict(status).get("is_export_active"):
+ return Stop(False, "No export is running.", job_id)
+ answer = await route_json("POST", "/api/export/cancel", caller = caller)
+ if not (isinstance(answer, dict) and _export_stopped(answer)):
+ return Stop(False, _message(answer), job_id)
+ return Stop(True, EXPORT_STOPPED, job_id)
+
+
+# Training phases by job status; any other phase means the run is still going.
+TRAINING_STATUS = {
+ "completed": "completed",
+ "error": "failed",
+ "stopped": "cancelled",
+ "idle": "idle",
+}
+
+
+async def _read_training(
+ kind: str, caller: Caller, job_id: Optional[str], **_unused: Any
+) -> ToolResult:
+ payload = as_dict(await route_json("GET", SLOT_ROUTES[kind], caller = caller))
+ slot = (_training if kind == "training" else _diffusion_training)(payload)
+ # An id that is not the current job (or one with nothing running) is never echoed back as idle.
+ if job_id and job_id != slot.job_id:
+ # list_training_runs reads LLM runs only.
+ where = (
+ f'; list_training_runs(run_id="{job_id}") has its result' if kind == "training" else ""
+ )
+ raise ToolError(f"{job_id} is not the current training job{where}")
+ phase = "running" if kind == "diffusion_training" and slot.phase == "busy" else slot.phase
+ status = TRAINING_STATUS.get(phase, "running")
+ training = TrainingJob(**slot.model_dump())
+ if status == "completed":
+ details = as_dict(payload.get("details")) if kind == "training" else payload
+ run, found = await _run_folder(caller, opt_text(details.get("output_dir")))
+ training = training.model_copy(
+ update = {
+ "run_folder": run,
+ "checkpoints": [c.name for c in found if run and c.run == run],
+ "loss_history": (
+ f'list_training_runs(run_id="{slot.job_id}")'
+ if kind == "training" and slot.job_id
+ else None
+ ),
+ }
+ )
+ return media_result(
+ [],
+ JobStatus(
+ kind = kind,
+ id = slot.job_id or job_id,
+ status = status,
+ progress_percent = slot.progress_percent,
+ error = slot.error,
+ training = training,
+ ),
+ )
+
+
+async def _run_folder(caller: Caller, output: Optional[str]) -> tuple[Optional[str], list]:
+ """The run folder name for a status ``output_dir``: an API key gets an opaque reference, matched like list_training_runs does."""
+ from hub.utils.host_paths import cache_reference
+
+ found, folders = await named.list_checkpoints(caller)
+ if not output:
+ return None, found
+ for folder, path in folders.items():
+ if output in (path, cache_reference(path)):
+ return folder, found
+ return (None if output.startswith("ref:") else leaf_name(output)), found
+
+
+async def _cancel_training(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ if not job_id:
+ status = await route_json("GET", "/api/train/status", caller = caller)
+ job_id = opt_text(status.get("job_id")) if isinstance(status, dict) else None
+ if not job_id or not (isinstance(status, dict) and status.get("is_training_running")):
+ return Stop(False, "No training job is running.", None)
+ answer = await route_json(
+ "POST",
+ "/api/train/stop",
+ caller = caller,
+ json_body = {"save": save, "expected_job_id": job_id},
+ )
+ return _outcome(answer, lambda a: a.get("status") == "stopped", job_id)
+
+
+def _diffusion_stopping(answer: dict) -> bool:
+ return answer.get("status") == "stopping"
+
+
+START_CANCELLED = "training_start_cancelled"
+
+
+def _start_withdrawn(answer: dict) -> bool:
+ # Rejected for another reason (a bad model, say) is not a cancel.
+ return answer.get("state") == "rejected" and answer.get("error_code") == START_CANCELLED
+
+
+def _load_status(job: loading.LoadJob) -> JobStatus:
+ return JobStatus(
+ kind = "load",
+ id = job.job_id,
+ status = job.status,
+ progress_percent = (
+ 100.0
+ if job.status == "completed"
+ else round(100.0 * job.fraction, 1)
+ if job.fraction is not None
+ else None
+ ),
+ error = job.error,
+ load = job.result if job.status == "completed" else None,
+ )
+
+
+async def _read_load(caller: Caller, job_id: Optional[str], **_unused: Any) -> ToolResult:
+ if job_id is None:
+ jobs = [
+ JobSummary(id = job.job_id, status = job.status)
+ for job in loading.LOADS.jobs_of(caller.account_id)
+ ]
+ return media_result([], JobStatus(kind = "load", jobs = jobs))
+ return media_result([], _load_status(loading.LOADS.lookup(caller.account_id, job_id)))
+
+
+async def _read_download(caller: Caller, job_id: Optional[str], **_unused: Any) -> ToolResult:
+ if not job_id:
+ raise ToolError('get_job(kind="download") needs id: the id download_model returned.')
+ return media_result([], await model_downloads.status(caller, job_id))
+
+
+async def _cancel_download(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ stopped, state = await model_downloads.cancel_parts(caller, job_id)
+ if stopped:
+ return Stop(True, "Unsloth Studio is stopping the download.", job_id)
+ return Stop(False, f"Nothing to stop: the download is {state or 'not found'}.", job_id)
+
+
+KEPT_TAKES = "finished takes stay in Audio history."
+_cancel_take = _route_cancel("/api/inference/audio/cancel", "cancel_id", _cancelled)
+
+
+async def _cancel_audio(caller: Caller, job_id: Optional[str], save: bool) -> Stop:
+ between = audio_runs.stop_run(caller.account_id, job_id)
+ if between:
+ return Stop(True, f"The run stops before its next take; {KEPT_TAKES}", job_id)
+ stop = await _cancel_take(caller, job_id, save)
+ if between is False:
+ # The route stopped the take in flight, or it just ended; either way no take follows.
+ return Stop(True, f"The run was stopped; {KEPT_TAKES}", job_id)
+ return stop
+
+
+register(Kind("video", read = _read_video, cancel = _cancel_video, poll_after_s = 15))
+register(
+ Kind(
+ "recipe",
+ read = _read_recipe,
+ cancel = _route_cancel(RECIPE_ROUTES + "/jobs/{id}/cancel", None, _recipe_cancelling),
+ poll_after_s = 10,
+ follows_current = True,
+ needs_id = "the recipe job id",
+ )
+)
+register(Kind("export", read = _read_export, cancel = _cancel_export, poll_after_s = 15))
+register(
+ Kind(
+ "training",
+ read = partial(_read_training, "training"),
+ cancel = _cancel_training,
+ poll_after_s = 30,
+ follows_current = True,
+ )
+)
+register(
+ Kind(
+ "diffusion_training",
+ read = partial(_read_training, "diffusion_training"),
+ cancel = _route_cancel("/api/train/diffusion/stop", "save", _diffusion_stopping),
+ poll_after_s = 30,
+ follows_current = True,
+ takes_id = False,
+ )
+)
+register(Kind("load", read = _read_load, poll_after_s = 10))
+register(
+ Kind(
+ "download",
+ read = _read_download,
+ cancel = _cancel_download,
+ poll_after_s = 15,
+ needs_id = "the id download_model returned",
+ ),
+ "model_download",
+)
+register(
+ Kind(
+ "training_start",
+ cancel = _route_cancel("/api/train/start-requests/{id}/cancel", None, _start_withdrawn),
+ needs_id = "the start request id",
+ )
+)
+register(
+ Kind(
+ "image",
+ cancel = _route_cancel("/api/inference/images/generate/cancel", None, _cancelled),
+ takes_id = False,
+ )
+)
+register(
+ Kind(
+ "chat",
+ cancel = _route_cancel("/api/inference/cancel", "cancel_id", _cancelled),
+ needs_id = "the chat's cancel_id",
+ )
+)
+register(
+ Kind(
+ "audio",
+ cancel = _cancel_audio,
+ needs_id = "the run's cancel_id (generate_audio returns it)",
+ )
+)
+register(
+ Kind(
+ "dataset_download",
+ cancel = _route_cancel("/api/hub/datasets/download/cancel", "repo_id", _cancelling),
+ needs_id = "the dataset's repo_id",
+ )
+)
diff --git a/studio/backend/studio_mcp/jobs.py b/studio/backend/studio_mcp/jobs.py
new file mode 100644
index 00000000000..1741ad7d980
--- /dev/null
+++ b/studio/backend/studio_mcp/jobs.py
@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every kind of long-running Unsloth Studio work behind one interface: ``follow`` reads a job and waits for it to move, ``cancel`` stops one. Each kind plugs in as a ``Kind`` registered here (the built-in ones in job_kinds); get_job and cancel only pick the kind."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, NamedTuple, Optional
+
+from fastmcp import Context
+from fastmcp.exceptions import ToolError
+from fastmcp.tools import ToolResult
+
+from studio_mcp import loading
+from studio_mcp.caller import Caller
+from studio_mcp.media import ReturnMedia, media_result
+from studio_mcp.outputs import CancelResult, JobStatus
+from studio_mcp.tools import as_dict
+
+
+class Stop(NamedTuple):
+ """What a cancel did: whether it stopped something, what to tell the agent, and the job it acted on."""
+
+ cancelled: bool
+ message: Optional[str]
+ id: Optional[str]
+
+
+# read(caller, job_id, rows = ..., offset = ..., return_media = ..., preview_px = ...)
+Read = Callable[..., Awaitable[ToolResult]]
+# cancel(caller, job_id, save)
+Cancel = Callable[[Caller, Optional[str], bool], Awaitable[Stop]]
+
+
+@dataclass(frozen = True)
+class Kind:
+ name: str
+ read: Optional[Read] = None
+ cancel: Optional[Cancel] = None
+ # Seconds a caller not using wait_s should leave before asking again.
+ poll_after_s: float = 15
+ # Without an id a read follows the current job rather than listing recent ones, so it can wait.
+ follows_current: bool = False
+ # What a cancel's id is, for a kind whose cancel needs one.
+ needs_id: Optional[str] = None
+ # False for a kind whose cancel stops whatever is running and takes no id.
+ takes_id: bool = True
+
+
+KINDS: dict[str, Kind] = {}
+
+
+def register(kind: Kind, *aliases: str) -> Kind:
+ """Plug in a kind of work; ``aliases`` name it too (a model download is "download" to read, "model_download" to cancel)."""
+ for name in (kind.name, *aliases):
+ KINDS[name] = kind
+ return kind
+
+
+def kind_of(name: str) -> Kind:
+ kind = KINDS.get(name)
+ if kind is None:
+ raise ToolError(f"Unknown job kind {name!r}")
+ return kind
+
+
+# The least time follow gives its first read and, at the end of a wait, its rows read.
+FIRST_READ_S = 30
+LAST_READ_S = 5
+# Job statuses that mean the job is still going; a wait waits only on these.
+RUNNING = {"running", "queued", "in_progress", "created", "pending", "active", "cancelling"}
+
+
+def _moment(structured: Any) -> tuple[Any, Any, Any]:
+ # (status, phase, percent): a wait ends when the first two change. Export has no percent, only a phase.
+ job = as_dict(structured)
+ phase = as_dict(job.get("export")).get("phase") or as_dict(job.get("training")).get("phase")
+ return job.get("status"), phase, job.get("progress_percent")
+
+
+async def follow(
+ caller: Caller,
+ name: str,
+ job_id: Optional[str],
+ *,
+ wait_s: int = 0,
+ ctx: Optional[Context] = None,
+ rows: Optional[int] = None,
+ offset: int = 0,
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
+) -> ToolResult:
+ """Read job ``job_id`` of kind ``name`` and, given ``wait_s``, wait for it to finish or move on."""
+ kind = kind_of(name)
+ if kind.read is None:
+ raise ToolError(f"Unknown job kind {name!r}")
+
+ def read(rows: Optional[int]) -> Awaitable[ToolResult]:
+ return kind.read(
+ caller,
+ job_id,
+ rows = rows,
+ offset = offset,
+ return_media = return_media,
+ preview_px = preview_px,
+ )
+
+ deadline = time.monotonic() + min(wait_s, loading.MAX_WAIT_S)
+ # Forwarded reads have no HTTP timeout, so each one here is bounded: the first by the wait (at
+ # least FIRST_READ_S), the polls and the final rows read by what is left of it.
+ first = max(min(wait_s, loading.MAX_WAIT_S), FIRST_READ_S)
+ try:
+ result = await asyncio.wait_for(read(rows), timeout = first)
+ except asyncio.TimeoutError:
+ raise ToolError(
+ f"Unsloth Studio did not report on the {name} job within {first:g} s; call get_job again"
+ ) from None
+ start = _moment(result.structured_content)
+ # A listing has nothing to wait on.
+ waits = job_id is not None or kind.follows_current
+ moved = polled = False
+ while waits and start[0] in RUNNING:
+ left = deadline - time.monotonic()
+ if left <= 0:
+ break
+ await asyncio.sleep(min(loading.POLL_INTERVAL_S, left))
+ try:
+ # Recipe rows are read once, for the answer, not on every poll; a read that stalls past
+ # the deadline ends the wait with the last answer.
+ latest = await asyncio.wait_for(
+ read(None), timeout = max(deadline - time.monotonic(), 0.01)
+ )
+ except asyncio.TimeoutError:
+ break
+ except Exception:
+ # Like a load's progress poll: a failed read during the wait is skipped.
+ continue
+ result, polled = latest, True
+ now = _moment(result.structured_content)
+ if now[:2] != start[:2]:
+ moved = True
+ break
+ if ctx is not None and now[2] is not None:
+ await ctx.report_progress(min(now[2] / 100.0, 1.0), 1.0, str(now[1] or now[0]))
+ if polled and rows:
+ try:
+ result = await asyncio.wait_for(
+ read(rows), timeout = max(deadline - time.monotonic(), LAST_READ_S)
+ )
+ except asyncio.TimeoutError:
+ pass # The answer goes out without rows; the next get_job reads them.
+ # A wait that ended because the job moved on can be followed again at once.
+ return _with_poll_after(result, 0 if moved else kind.poll_after_s)
+
+
+def _with_poll_after(result: ToolResult, after: float) -> ToolResult:
+ structured = as_dict(result.structured_content)
+ if structured.get("status") not in RUNNING or structured.get("jobs") is not None:
+ return result
+ status = JobStatus.model_validate({**structured, "poll_after_s": after})
+ return media_result(list(result.content[1:]), status)
+
+
+async def cancel(
+ caller: Caller,
+ name: str,
+ job_id: Optional[str],
+ save: bool = True,
+) -> CancelResult:
+ """Stop job ``job_id`` of kind ``name``; ``cancelled`` says whether this call stopped something."""
+ kind = kind_of(name)
+ if kind.cancel is None:
+ raise ToolError(f"Unknown job kind {name!r}")
+ if kind.needs_id and not job_id:
+ raise ToolError(f"cancel(kind={name!r}) needs id: {kind.needs_id}.")
+ if not kind.takes_id and job_id:
+ raise ToolError(
+ f"cancel(kind={name!r}) takes no id: this cancel stops the running one; leave id out."
+ )
+ stop = await kind.cancel(caller, job_id, save)
+ return CancelResult(kind = name, id = stop.id, cancelled = stop.cancelled, message = stop.message)
+
+
+from studio_mcp import job_kinds as _built_in # noqa: E402,F401 registers the built-in kinds
diff --git a/studio/backend/studio_mcp/loading.py b/studio/backend/studio_mcp/loading.py
index b65893f667d..0eb5a001360 100644
--- a/studio/backend/studio_mcp/loading.py
+++ b/studio/backend/studio_mcp/loading.py
@@ -13,12 +13,12 @@ import os
import time
import uuid
from dataclasses import dataclass, field
-from pathlib import Path
from typing import Any, Awaitable, Callable, Optional
from fastmcp import Context
from fastmcp.exceptions import ToolError
+from core.inference import model_identity
from studio_mcp import job_store
from studio_mcp import placement as place
from studio_mcp.caller import Caller
@@ -116,34 +116,13 @@ def deadline_after(wait_s: Optional[float]) -> float:
return time.monotonic() + wait
-def _is_path(name: str) -> bool:
- if name.startswith(("/", "~", ".")) or "\\" in name or name[1:3] in (":/", ":\\"):
- return True
- # A relative path (models/Foo.gguf) reads like a Hub id; one that exists on disk is a path.
- try:
- return Path(name).expanduser().exists()
- except (OSError, ValueError):
- return False
-
-
def _same(left: Optional[str], right: Optional[str]) -> bool:
- # Hub ids match in any case; a local path keeps the file system's case.
- if not left or not right:
- return False
- return left == right if _is_path(left) or _is_path(right) else left.lower() == right.lower()
-
-
-def _repo(name: str) -> str:
- # A GGUF is listed as repo:variant in one place and the bare repo in another. A local path
- # (C:\models\a.gguf) has a drive letter there, not a variant, and a ref: handle is one opaque id.
- if name.startswith("ref:"):
- return name
- head, sep, tail = name.partition(":")
- return head if sep and len(head) > 1 and "/" not in tail and "\\" not in tail else name
+ # A relative path that exists on disk keeps its case, as the loaders read it.
+ return model_identity.same_model(left, right, probe = True)
def _same_id(left: str, right: str) -> bool:
- return _same(left, right) or _same(_repo(left), _repo(right))
+ return model_identity.same_repo(left, right, probe = True)
def _in_flight(caller: Caller, asked: LoadJob) -> Optional[LoadJob]:
@@ -151,7 +130,7 @@ def _in_flight(caller: Caller, asked: LoadJob) -> Optional[LoadJob]:
if (
job.slot == asked.slot
and _same(job.model, asked.model)
- and (job.variant or "").lower() == (asked.variant or "").lower()
+ and model_identity.same_variant(job.variant, asked.variant)
and job.options == asked.options
):
return job
@@ -360,7 +339,7 @@ def _llm_poll(caller: Caller, model: str) -> Callable[[], Awaitable[Progress]]:
fraction = number(loading.get("fraction")) if isinstance(loading, dict) else None
if fraction and opt_text(loading.get("phase")):
return min(fraction, 1.0), f"Loading into memory ({loading['phase']})"
- if model.startswith(("/", "\\", "ref:")) or ":" in model[:3]:
+ if model_identity.is_local(model):
return None
download = await route_json(
"GET",
@@ -569,6 +548,7 @@ def _resident_matches(
if not isinstance(status, dict) or status.get("loaded") is not True:
return False
names = {opt_text(status.get("repo_id")), opt_text(status.get("display_repo_id"))}
+ # Any case, paths too: status may spell the resident path differently from the request.
if model.lower() not in {name.lower() for name in names if name}:
return False
# Another file of the same repo is another model: a missing field reads as not loaded yet.
@@ -581,16 +561,13 @@ def _resident_matches(
resident = opt_text(status.get("gguf_filename"))
if resident:
return os.path.normcase(resident) == os.path.normcase(wanted)
- from hub.utils.gguf import extract_quant_token, quant_token_with_bpw
-
# Video status names only a GGUF's quant; a plain checkpoint has none to compare.
- quant = extract_quant_token(wanted) if wanted.lower().endswith(".gguf") else None
- if not quant:
+ quant = model_identity.resident_quant_matches(
+ opt_text(status.get("gguf_variant")), wanted, settled = settled
+ )
+ if quant is None:
return True
- if (opt_text(status.get("gguf_variant")) or "").lower() != quant.lower():
- return False
- # Status drops a -3.97bpw style suffix, so until the load reports ready a sibling build matches too.
- if not settled and quant_token_with_bpw(wanted) != quant:
+ if not quant:
return False
# MiniMax-H3 ships its fl2va and ref2va partitions at the same quant; status names the one loaded.
h3_task = opt_text(status.get("h3_task"))
diff --git a/studio/backend/studio_mcp/media.py b/studio/backend/studio_mcp/media.py
index 02531fa7ffe..8d97e93c63d 100644
--- a/studio/backend/studio_mcp/media.py
+++ b/studio/backend/studio_mcp/media.py
@@ -47,13 +47,21 @@ def resource_link(
url: str,
name: str,
mime: Optional[str] = None,
-) -> ResourceLink:
+) -> Union[ResourceLink, TextContent]:
+ """A resource link to ``url``. A chat call has no outer request, so its links are origin-relative,
+ which a ResourceLink cannot hold: those come back as the link in plain text instead."""
+ if not urlsplit(url).scheme:
+ return TextContent(type = "text", text = f"{name}: {url}")
return ResourceLink(type = "resource_link", uri = url, name = name, mimeType = mime)
def _base(caller: Caller) -> str:
"""The outer request's base, with the tunnel's scheme when it came through cloudflared, which reaches Unsloth Studio over plain http."""
+ if not caller.public_base:
+ return ""
base = urlsplit(caller.public_base)
+ if not base.scheme:
+ return base.path.rstrip("/")
tunnel = getattr(getattr(caller.studio_app, "state", None), "cloudflare_url", None)
if isinstance(tunnel, str) and tunnel:
published = urlsplit(tunnel)
diff --git a/studio/backend/studio_mcp/model_downloads.py b/studio/backend/studio_mcp/model_downloads.py
index 9cd036953c8..81dd887d433 100644
--- a/studio/backend/studio_mcp/model_downloads.py
+++ b/studio/backend/studio_mcp/model_downloads.py
@@ -14,6 +14,9 @@ from typing import Any, Optional
from fastmcp import Context
from fastmcp.exceptions import ToolError
+from core.inference import model_identity
+from studio_mcp.problems import caller_tools
+from studio_mcp.surface import render
from studio_mcp import loading
from studio_mcp import placement as place
from studio_mcp.caller import Caller
@@ -104,7 +107,7 @@ def _worst(states: list[str]) -> str:
def _looks_local(model: str) -> bool:
# A host path, or the ref: handle a checkpoint or export load sends.
- return model.startswith(("/", "\\", ".", "ref:")) or ":" in model[:3]
+ return model_identity.is_local(model)
def _split(model: str, variant: Optional[str]) -> tuple[str, Optional[str]]:
@@ -179,8 +182,11 @@ async def _plan_parts(
raise tool_error(plan["incompatible_reason"])
if plan.get("plan_failed"):
raise ToolError(
- f"Unsloth Studio could not list the files {model} needs, so it can't download them ahead of time. "
- "Call load_model, which downloads while it loads."
+ render(
+ f"Unsloth Studio could not list the files {model} needs, so it can't download them ahead of time. "
+ "<<load_model: Call load_model, which downloads while it loads. | Loading it downloads it.>>",
+ caller_tools(),
+ )
)
entries = [as_dict(e) for e in plan.get("entries") or []]
return [
@@ -420,8 +426,12 @@ async def wait_for_managed(
left = None if deadline is None else deadline - time.monotonic()
if left is not None and left <= 0:
raise ToolError(
- f"Unsloth Studio is still downloading {model}. "
- f'Follow it with get_job(kind="download", id="{format_id(keys)}"), then call load_model again.'
+ render(
+ f"Unsloth Studio is still downloading {model}. "
+ f'Follow it with get_job(kind="download", id="{format_id(keys)}")'
+ "<<load_model: , then call load_model again>>.",
+ caller_tools(),
+ )
)
if ctx is not None:
follow = f'get_job(kind="download", id="{format_id(keys)}")'
diff --git a/studio/backend/studio_mcp/placement.py b/studio/backend/studio_mcp/placement.py
index e69e080d894..490a805547c 100644
--- a/studio/backend/studio_mcp/placement.py
+++ b/studio/backend/studio_mcp/placement.py
@@ -11,6 +11,7 @@ from typing import Any, Optional
from fastmcp.exceptions import ToolError
+from core.inference import model_identity
from studio_mcp.caller import Caller
from studio_mcp.errors import raise_for_route, tool_error
from studio_mcp.forward import forward
@@ -38,8 +39,6 @@ MEDIA_PROGRESS = {
"video": "/api/inference/video/load-progress",
}
STT_STATUS = "/api/inference/audio/stt/status"
-# audio.cpp folder ids name a GGUF repo but run on audio.cpp, which honours audio_device itself.
-AUDIO_CPP_PREFIX = "audio-cpp/audio.cpp-gguf/"
IN_FLIGHT = ("running", "cancelling")
READ_S = 15.0
PARTIAL_MESSAGE = "this variant is still downloading or incomplete; wait for it or redownload it"
@@ -57,7 +56,7 @@ def media_knobs(kind: str, **knobs: Optional[str]) -> dict[str, str]:
def is_local(model: str) -> bool:
# A host path, or the ref:<digest> handle of a local model (API-key callers, checkpoint and export loads): whole, never repo:variant.
- return model.startswith(("/", "\\", ".", "~", "ref:")) or ":" in model[:3]
+ return model_identity.is_local(model)
def is_gguf(model: str, variant: Optional[str]) -> bool:
@@ -99,7 +98,7 @@ CPU_NEEDS_GGUF = (
async def listed_gguf(caller: Caller, model: str, variant: Optional[str]) -> Optional[bool]:
"""Whether the load runs on llama-server: Unsloth Studio lists GGUF files for the model (a name with "gguf" in it proves nothing). audio.cpp models never do. None when the listing could not be read."""
repo, variant = _split(model, variant)
- if repo.lower().startswith(AUDIO_CPP_PREFIX):
+ if model_identity.is_audio_cpp(repo):
return False
if repo.startswith("ref:") and variant:
# A trained GGUF export's handle carries its quantization; any other ref: the listing decides.
@@ -267,7 +266,7 @@ async def refuse_partial_variant(
caller: Caller, model: str, kind: str, variant: Optional[str]
) -> None:
"""Refuse a GGUF variant with only part of its files on disk that Unsloth Studio is not downloading itself; loading it fails with a misleading memory error."""
- if kind == "stt" or is_local(model) or model.lower().startswith(AUDIO_CPP_PREFIX):
+ if kind == "stt" or is_local(model) or model_identity.is_audio_cpp(model):
return
repo, variant = _split(model, variant)
# A chat model is a GGUF when the listing has rows, whatever it is called; an image or video
@@ -323,15 +322,6 @@ def _cpu_primary(status: Any) -> bool:
return manual or status.get("audio_device_fallback") == "cpu"
-def _ident(name: str) -> str:
- # Local paths keep their case, as the loaders do; Hub ids do not.
- return name if is_local(name) else name.lower()
-
-
-def _repo(name: str) -> str:
- return name if is_local(name) else name.split(":", 1)[0].lower()
-
-
def predict(
*,
kind: str,
@@ -347,9 +337,18 @@ def predict(
slot_kind = "llm" if kind in CHAT_KINDS else kind
if kind == "stt":
# A speech-to-text load releases the other engines' models, unless one is transcribing.
- others = [s for s in slots if s.kind == "stt" and _ident(s.model) != _ident(model)]
+ others = [
+ s
+ for s in slots
+ if s.kind == "stt" and not model_identity.same_model(s.model, model, probe = True)
+ ]
return others, not others, False
- same_repo = [s for s in slots if s.kind == slot_kind and _repo(s.model) == _repo(model)]
+ # Local paths keep their case, as the loaders do (an existing relative one too); Hub ids do not.
+ same_repo = [
+ s
+ for s in slots
+ if s.kind == slot_kind and model_identity.same_repo(s.model, model, probe = True)
+ ]
# A load of a resident repo may load it again (another variant, context, device or build), so it
# is predicted as a new load and reported as an upper bound.
exact = not same_repo
diff --git a/studio/backend/studio_mcp/problems.py b/studio/backend/studio_mcp/problems.py
new file mode 100644
index 00000000000..9cf23547531
--- /dev/null
+++ b/studio/backend/studio_mcp/problems.py
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A route's machine code for a failure, and what the agent should do next.
+
+Routes name the state in the ``X-Unsloth-Problem`` header (``code k=v``) or in the code field of
+their error body; nothing here reads the English. The next step is an action, rendered against
+the tools the caller has, so a hint never names a tool the caller cannot call."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+from core.inference.ensure_model import PAGES
+
+PROBLEM_HEADER = "x-unsloth-problem"
+_CODE = re.compile(r"^[a-z][a-z0-9_]{1,63}$")
+# Fields the tag repeats, per code: the rest stay in the message.
+TAG_FIELDS = {
+ "not_loaded": ("kind",),
+ "needs_user_load": ("kind", "page"),
+ "needs_download": ("kind",),
+ "multi_model_always": ("kind",),
+}
+WHAT = {
+ "llm": "chat model",
+ "tts": "text-to-speech or music model",
+ "audio": "text-to-speech or music model",
+ "stt": "speech-to-text model",
+ "image": "image model",
+ "video": "video model",
+}
+# load_model's kind for each not_loaded kind; a music model loads as tts.
+LOAD_KINDS = {"tts": "tts", "audio": "tts", "stt": "stt", "image": "image", "video": "video"}
+# multi_model_always names the slot as the arbiter does (chat); unload_model calls it llm.
+UNLOAD_KINDS = {"chat": "llm", "audio": "audio", "image": "image", "video": "video"}
+
+_UPDATE_AUDIO_RUNTIME = (
+ "Update the audio runtime (`unsloth studio update`), then load the model again."
+)
+
+
+@dataclass(frozen = True)
+class Problem:
+ code: str
+ fields: Mapping[str, str] = field(default_factory = dict)
+
+ def tag_fields(self) -> dict[str, str]:
+ keys = TAG_FIELDS.get(self.code, ())
+ return {key: self.fields[key] for key in keys if key in self.fields}
+
+
+def parse(value: Any) -> Optional[Problem]:
+ """``code k=v ...`` as a route sent it; None for anything else."""
+ if not isinstance(value, str):
+ return None
+ code, *pairs = value.split()
+ if not _CODE.match(code):
+ return None
+ fields = dict(pair.split("=", 1) for pair in pairs if "=" in pair)
+ return Problem(code, fields)
+
+
+def from_headers(headers: Mapping[str, str]) -> Optional[Problem]:
+ return parse(headers.get(PROBLEM_HEADER))
+
+
+def caller_tools() -> frozenset[str]:
+ """The tools the current caller's profile offers, less those the owner turned off."""
+ from mcp_server import surface
+ from studio_mcp.caller import current_caller
+ from studio_mcp.profile import AGENT
+ from utils import mcp_access
+
+ try:
+ profile = current_caller().profile
+ except RuntimeError:
+ profile = AGENT
+ # A hint must not name a tool the access middleware refuses; cached, so cheap on the loop.
+ disabled = mcp_access.disabled_tools()
+ return frozenset() if disabled is None else surface(profile) - disabled
+
+
+def _ask_user_load(kind: str, model: Optional[str] = None) -> str:
+ page = PAGES.get(kind, "Chat")
+ what = f"'{model}'" if model else f"a {WHAT.get(kind, 'model')}"
+ return f"Ask the user to load {what} on the {page} page in Unsloth Studio, then try again."
+
+
+def download_hint(kind: str, model: Optional[str], tools: frozenset[str]) -> str:
+ if "download_model" not in tools or not model:
+ return _ask_user_load(kind, model)
+ return (
+ f"Call download_model(model='{model}', kind='{kind}'), follow it with "
+ "get_job(kind='download', id=<its id>), then try again."
+ )
+
+
+def load_hint(kind: str, tools: frozenset[str]) -> str:
+ if "load_model" not in tools:
+ return _ask_user_load(kind)
+ if kind in ("llm", "chat"):
+ return "Load a chat model with load_model first; list_models shows the downloaded ones."
+ load_kind = LOAD_KINDS.get(kind, kind)
+ article = "an" if WHAT.get(kind, "model")[0] in "aeiou" else "a"
+ return f"Load {article} {WHAT.get(kind, 'model')} with load_model(kind='{load_kind}') first."
+
+
+def unload_hint(kind: Optional[str], tools: frozenset[str]) -> str:
+ unload = UNLOAD_KINDS.get(kind or "")
+ if "unload_model" in tools:
+ if unload is None:
+ return (
+ "Call unload_model(kind=…) for the model it names to free the GPU; "
+ "retrying won't help."
+ )
+ return f"Call unload_model(kind='{unload}') to free the GPU; retrying won't help."
+ return (
+ "Ask the user to unload the model it names in Unsloth Studio, or to choose When they fit; "
+ "retrying won't help."
+ )
+
+
+def wait_hint(tools: frozenset[str]) -> str:
+ if "cancel" in tools:
+ return (
+ "Wait for the running chats to finish, or cancel a chat you started with"
+ " cancel(kind='chat', id=<its cancel_id>)."
+ )
+ return "Wait for the running chats to finish, then try again."
+
+
+def hint(problem: Problem, tools: frozenset[str]) -> Optional[str]:
+ kind = problem.fields.get("kind")
+ if problem.code == "not_loaded":
+ return load_hint(kind or "llm", tools)
+ if problem.code == "needs_user_load":
+ # The route's message already says what the user must do and why.
+ return None
+ if problem.code == "needs_download":
+ return download_hint(kind or "llm", problem.fields.get("model"), tools)
+ if problem.code == "multi_model_always":
+ return unload_hint(kind, tools)
+ if problem.code == "active_generations":
+ return wait_hint(tools)
+ return None
+
+
+def audio_hint(code: str, smaller_variants: list[str], tools: frozenset[str]) -> Optional[str]:
+ """What to do about a coded audio runtime failure."""
+ if code in ("runtime_missing", "family_unknown_to_runtime", "espeak_missing"):
+ return _UPDATE_AUDIO_RUNTIME
+ if code == "file_incomplete":
+ return "Download the model again, or load another variant."
+ loads = "load_model" in tools
+ if code == "runtime_stopped":
+ if loads:
+ return (
+ "Retry once; if it fails again, run studio_status and load_model the audio "
+ "model again."
+ )
+ return (
+ "Retry once; if it fails again, ask the user to reload the audio model in "
+ "Unsloth Studio."
+ )
+ if code in ("out_of_memory", "gpu_unavailable"):
+ if not loads:
+ return "Ask the user to reload the audio model on the CPU in Unsloth Studio."
+ variants = (
+ f", or a smaller variant with load_model(variant=...): {', '.join(smaller_variants)}"
+ if code == "out_of_memory" and smaller_variants
+ else ""
+ )
+ return f"Load the audio model again with device='cpu'{variants}."
+ return None
+
+
+AUDIO_CODES = frozenset(
+ (
+ "out_of_memory",
+ "gpu_unavailable",
+ "runtime_missing",
+ "family_unknown_to_runtime",
+ "espeak_missing",
+ "runtime_stopped",
+ "file_incomplete",
+ )
+)
diff --git a/studio/backend/studio_mcp/profile.py b/studio/backend/studio_mcp/profile.py
new file mode 100644
index 00000000000..3f083c2f342
--- /dev/null
+++ b/studio/backend/studio_mcp/profile.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Who an MCP call answers to, and what follows from it: the tools it is offered, whether host
+files are reachable, and whether its key outlives the call. Tool modules only declare facts about
+their tools (``FACTS``); a profile withholds the tools whose facts it cannot allow."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Collection, Mapping
+
+SWAPS_MODELS = "swaps_models"
+PREVIEWS_SWAPS = "previews_swaps"
+REENTERS_CHAT = "reenters_chat"
+STOPS_WORK = "stops_work"
+OUTLIVES_CALL = "outlives_call"
+SENDS_HOST_SECRETS = "sends_host_secrets"
+
+REASONS = {
+ SWAPS_MODELS: "it could unload the model serving the chat",
+ PREVIEWS_SWAPS: "it previews load_model, which a chat does not have",
+ REENTERS_CHAT: "it would re-enter the chat that calls it",
+ STOPS_WORK: "it could stop the chat that calls it",
+ OUTLIVES_CALL: "it keeps working after the chat's per-call key is revoked",
+ SENDS_HOST_SECRETS: "it can send host credentials and files to an endpoint a prompt names",
+}
+
+
+@dataclass(frozen = True)
+class CallerProfile:
+ name: str
+ # Facts a tool may not have for this caller to be offered it.
+ refused: frozenset[str] = frozenset()
+ # The key ends with the tool call, so nothing may keep it for later work.
+ call_scoped: bool = False
+ # Host file paths may be read when the request itself comes from this computer.
+ host_files: bool = True
+ prompts: bool = True
+
+ def withheld(self, facts: Mapping[str, Collection[str]]) -> dict[str, str]:
+ """Each withheld tool with the reason, in ``facts`` order."""
+ return {
+ name: REASONS[fact]
+ for name, tool_facts in facts.items()
+ for fact in sorted(self.refused & set(tool_facts))[:1]
+ }
+
+ def tools(self, facts: Mapping[str, Collection[str]], names: Collection[str]) -> frozenset[str]:
+ return frozenset(names) - set(self.withheld(facts))
+
+
+AGENT = CallerProfile("agent")
+CHAT = CallerProfile(
+ "chat",
+ refused = frozenset(REASONS),
+ call_scoped = True,
+ # A prompt-injected model must not reach host files, even the owner's.
+ host_files = False,
+ prompts = False,
+)
diff --git a/studio/backend/studio_mcp/surface.py b/studio/backend/studio_mcp/surface.py
new file mode 100644
index 00000000000..d42ec272a11
--- /dev/null
+++ b/studio/backend/studio_mcp/surface.py
@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tool text for one caller's surface. ``<<tool: shown with it | shown without it>>`` in a docstring,
+hint or field description keeps a caller from reading about a tool it was not given."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Collection
+
+_SEGMENT = re.compile(r"<<(\w+): (.*?)(?: \| (.*?))?>>", re.DOTALL)
+
+
+def render(text: Any, tools: Collection[str]) -> Any:
+ if not isinstance(text, str) or "<<" not in text:
+ return text
+ rendered = _SEGMENT.sub(
+ lambda match: match.group(2) if match.group(1) in tools else (match.group(3) or ""),
+ text,
+ )
+ # A dropped segment may leave a doubled or trailing space before punctuation.
+ return re.sub(r" {2,}", " ", re.sub(r" +([.,;:)])(?=\s|$)", r"\1", rendered)).strip()
+
+
+def render_schema(schema: Any, tools: Collection[str]) -> Any:
+ """``render`` every string in a JSON schema, so field descriptions follow the same rule."""
+ if isinstance(schema, dict):
+ return {key: render_schema(value, tools) for key, value in schema.items()}
+ if isinstance(schema, list):
+ return [render_schema(value, tools) for value in schema]
+ return render(schema, tools)
diff --git a/studio/backend/studio_mcp/tools/audio.py b/studio/backend/studio_mcp/tools/audio.py
index 971f30f7e00..c9167447bc7 100644
--- a/studio/backend/studio_mcp/tools/audio.py
+++ b/studio/backend/studio_mcp/tools/audio.py
@@ -10,7 +10,6 @@ import base64
import binascii
import time
import uuid
-from dataclasses import dataclass
from typing import Annotated, Any, Literal, Optional
from fastmcp import Context
@@ -19,6 +18,7 @@ from fastmcp.tools import ToolResult
from pydantic import Field
from studio_mcp import loading
+from studio_mcp.audio_runs import _CANCELLED, _RUNS, _Run, _forget_old_cancels
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import raise_for_audio, raise_for_route
from studio_mcp.forward import forward, ndjson_last
@@ -43,8 +43,6 @@ from studio_mcp.outputs import (
from studio_mcp.progress import with_heartbeat
from studio_mcp.tools import WRITES, opt_text, present, route_json, strings, try_json
-LOAD_AUDIO_HINT = "Load a text-to-speech or music model with load_model(kind='tts') first."
-NOT_LOADED = "No model loaded"
# 16-bit samples; channels are not reported, so mono is assumed and a stereo clip may still be fetched and then linked.
_WAV_BYTES_PER_SAMPLE = 2
@@ -65,20 +63,62 @@ async def _clip_contents(
return [resource_link(clip.download_url or clip.url, f"{clip.id}.wav", "audio/wav")]
+# Workflows a model must list to serve; any other speech model can try the rest, as the route routes them.
+_DEDICATED = frozenset({"music", "separate", "transcribe"})
+
+
+def _serves(status: dict, workflow: str) -> bool:
+ workflows = strings(status.get("audio_workflows"))
+ if workflow == "music":
+ return bool(status.get("audio_music")) or "music" in workflows
+ if workflow in _DEDICATED:
+ return workflow in workflows
+ by_workflow = status.get("audio_options_by_workflow")
+ if status.get("audio_options") or (isinstance(by_workflow, dict) and by_workflow.get(workflow)):
+ return True
+ return bool(status.get("is_audio")) and any(w not in _DEDICATED for w in workflows or ["speak"])
+
+
+def _names(status: dict, model: str) -> bool:
+ return model.split(":", 1)[0].lower() in {
+ str(status.get(key) or "").lower() for key in ("model_identifier", "active_model")
+ }
+
+
+async def _audio_status(caller: Caller, workflow: str, model: Optional[str]) -> Optional[dict]:
+ """Status of the loaded model that will run ``workflow``: the named one, else the one the route
+ picks (the primary, or the one model for it kept beside the chat model). None when unknown,
+ such as a named model that is not loaded yet."""
+ if model:
+ status = await try_json(caller, "/api/inference/status", params = {"model": model})
+ return status if isinstance(status, dict) and _names(status, model) else None
+ status = await try_json(caller, "/api/inference/status")
+ if not isinstance(status, dict) or _serves(status, workflow):
+ return status
+ serving = strings(status.get("serving"))
+ checkpoints = strings(status.get("serving_checkpoints"))
+ found = []
+ for index, name in enumerate(serving):
+ routing_id = checkpoints[index] if index < len(checkpoints) else name
+ if not routing_id or name == status.get("active_model"):
+ continue
+ kept = await try_json(caller, "/api/inference/status", params = {"model": routing_id})
+ if isinstance(kept, dict) and kept.get("active_model") != status.get("active_model"):
+ if _serves(kept, workflow):
+ found.append(kept)
+ return found[0] if len(found) == 1 else None
+
+
async def _checked_options(
caller: Caller,
workflow: str,
options: dict[str, Any],
model: Optional[str] = None,
) -> dict[str, Any]:
- """``options`` with each enum value spelled as the loaded model lists it; the route drops a value it does not list, so that is refused here instead."""
- status = await try_json(caller, "/api/inference/status")
- if not isinstance(status, dict):
- return options
- if model and model.split(":", 1)[0].lower() not in {
- str(status.get(key) or "").lower() for key in ("model_identifier", "active_model")
- }:
- # Another model will run it, so the loaded model's choices say nothing about these.
+ """``options`` with each enum value spelled as the running model lists it; the route drops a value it does not list, so that is refused here instead."""
+ status = await _audio_status(caller, workflow, model)
+ if status is None:
+ # Not loaded yet, or not ours to guess: its choices are unknown here.
return options
by_workflow = status.get("audio_options_by_workflow")
schema = (by_workflow.get(workflow) if isinstance(by_workflow, dict) else None) or status.get(
@@ -103,48 +143,15 @@ async def _checked_options(
return checked
-@dataclass
-class _Run:
- cancelled: bool = False
- in_flight: bool = False
-
-
-# generate_audio runs by (account, cancel_id), and ids cancelled lately; the route keeps an early
-# cancel as long, so a reused id would be stopped on arrival.
-_RUNS: dict[tuple[str, str], _Run] = {}
-_CANCELLED: dict[tuple[str, str], float] = {}
-CANCEL_MEMORY_S = 30.0
-
-
-def _forget_old_cancels() -> None:
- cutoff = time.monotonic() - CANCEL_MEMORY_S
- for key in [key for key, at in _CANCELLED.items() if at < cutoff]:
- del _CANCELLED[key]
-
-
-def stop_run(account: str, cancel_id: str) -> Optional[bool]:
- """Mark run ``cancel_id`` cancelled: None when no generate_audio run here has that id, True when it stops between takes, False when a take is running and the route must stop it."""
- _forget_old_cancels()
- _CANCELLED[(account, cancel_id)] = time.monotonic()
- run = _RUNS.get((account, cancel_id))
- if run is None:
- return None
- run.cancelled = True
- return not run.in_flight
-
-
async def _post_run(caller: Caller, body: dict[str, Any]) -> Any:
response = await forward(caller, "POST", "/v1/audio/run", json_body = body)
- named = response.status_code == 400 and NOT_LOADED in response.text
- return raise_for_audio(response, hints = {400: LOAD_AUDIO_HINT} if named else None)
+ return raise_for_audio(response)
async def _takes_how(caller: Caller, body: dict[str, Any]) -> Optional[str]:
- """How the loaded music model makes variations of this mode: "batch", "sequential" or None."""
- status = await try_json(caller, "/api/inference/status")
- if not isinstance(status, dict):
- return None
- if body.get("model") and body["model"] != status.get("model_identifier"):
+ """How the running music model makes variations of this mode: "batch", "sequential" or None."""
+ status = await _audio_status(caller, "music", body.get("model"))
+ if status is None:
return None
music = status.get("audio_music")
modes = music.get("modes") if isinstance(music, dict) else None
@@ -266,8 +273,8 @@ async def generate_audio(
min_length = 8,
max_length = 64,
pattern = r"^[A-Za-z0-9_-]+$",
- description = "Your id for this run, so cancel(kind='audio', id=...) can stop it from "
- "another call; made when omitted and returned as cancel_id.",
+ description = "Your id for this run<<cancel: , so cancel(kind='audio', id=...) can stop it from "
+ "another call>>; made when omitted and returned as cancel_id.",
),
] = None,
edit: Optional[dict[str, Any]] = None,
diff --git a/studio/backend/studio_mcp/tools/cancel.py b/studio/backend/studio_mcp/tools/cancel.py
index 20484fedd05..2ed35fe9afc 100644
--- a/studio/backend/studio_mcp/tools/cancel.py
+++ b/studio/backend/studio_mcp/tools/cancel.py
@@ -5,16 +5,13 @@
from __future__ import annotations
-from typing import Any, Literal, Optional
-from urllib.parse import quote
+from typing import Literal, Optional
-from fastmcp.exceptions import ToolError
-
-from studio_mcp import export_jobs, job_store, model_downloads, video_queue
+from studio_mcp import profile
+from studio_mcp import jobs
from studio_mcp.caller import current_caller
from studio_mcp.outputs import CancelResult
-from studio_mcp.tools import DESTRUCTIVE, EXPORT_STATUS, as_dict, opt_text, route_json
-from studio_mcp.tools.audio import stop_run
+from studio_mcp.tools import DESTRUCTIVE
CancelKind = Literal[
"training",
@@ -29,80 +26,6 @@ CancelKind = Literal[
"dataset_download",
"model_download",
]
-START_CANCELLED = "training_start_cancelled"
-NEEDS_ID = {
- "training_start": "the start request id",
- "recipe": "the recipe job id",
- "chat": "the chat's cancel_id",
- "audio": "the run's cancel_id (generate_audio returns it)",
- "dataset_download": "the dataset's repo_id",
- "model_download": "the id download_model returned",
-}
-# The route each other kind posts to, and the body field that carries its id (or ``save``), if any.
-ROUTES = {
- "training_start": ("/api/train/start-requests/{id}/cancel", None),
- "diffusion_training": ("/api/train/diffusion/stop", "save"),
- "recipe": ("/api/data-recipe/jobs/{id}/cancel", None),
- "image": ("/api/inference/images/generate/cancel", None),
- "video": ("/api/inference/video/generate/cancel", "video_id"),
- "chat": ("/api/inference/cancel", "cancel_id"),
- "audio": ("/api/inference/audio/cancel", "cancel_id"),
- "dataset_download": ("/api/hub/datasets/download/cancel", "repo_id"),
-}
-
-
-def _message(answer: Any) -> Optional[str]:
- if isinstance(answer, dict):
- return opt_text(answer.get("message")) or opt_text(answer.get("status"))
- return None
-
-
-def _stopped(kind: str, answer: Any) -> bool:
- """Whether the route says it stopped something. Each route answers an idle cancel normally, so success alone means nothing."""
- if not isinstance(answer, dict):
- return False
- if kind in ("image", "video", "chat", "audio"):
- return bool(answer.get("cancelled"))
- if kind == "training":
- return answer.get("status") == "stopped"
- if kind == "training_start":
- # Rejected for another reason (a bad model, say) is not a cancel.
- return answer.get("state") == "rejected" and answer.get("error_code") == START_CANCELLED
- if kind == "diffusion_training":
- return answer.get("status") == "stopping"
- if kind == "export":
- return answer.get("message") == "Export cancelled"
- # "cancelled" here is a job that had already ended; only "cancelling" means this call stopped it.
- if kind == "recipe":
- return answer.get("status") == "cancelling"
- return answer.get("state") == "cancelling"
-
-
-KEPT_TAKES = "finished takes stay in Audio history."
-# How long a cancel waits for a job whose export just finished to record its own result.
-SETTLE_S = 2.0
-
-
-async def _cancel_export_job(caller: Any, job: export_jobs.ExportJob) -> tuple[bool, str]:
- """Stop only this job's own step: the route stops the worker when that op runs and otherwise refuses it when it starts."""
- for _ in range(3):
- op_id = job.op_id
- if op_id is None:
- break
- answer = await route_json(
- "POST", "/api/export/cancel", caller = caller, json_body = {"expected_op_id": op_id}
- )
- if _stopped("export", answer):
- job_store.mark_cancelled(job)
- return True, "The export was stopped and its checkpoint unloaded."
- # Its step just ended, or is queued behind someone else's: let a finished job report itself.
- await job_store.settle(job, SETTLE_S)
- if job.finished:
- return False, f"The export already {job.status}."
- if job.op_id == op_id:
- break
- job_store.mark_cancelled(job)
- return True, "The export job was stopped before its next step."
async def cancel(
@@ -123,69 +46,9 @@ async def cancel(
"model_download" stops the model download ``id`` that download_model returned; a speech-to-text download can't be stopped here.
``cancelled`` says whether this call stopped something.
"""
- caller = current_caller()
-
- def done(cancelled: bool, message: Optional[str]) -> CancelResult:
- return CancelResult(kind = kind, id = id, cancelled = cancelled, message = message)
+ return await jobs.cancel(current_caller(), kind, id, save)
- if kind in NEEDS_ID and not id:
- raise ToolError(f"cancel(kind={kind!r}) needs id: {NEEDS_ID[kind]}.")
- if kind in ("image", "diffusion_training") and id:
- raise ToolError(
- f"cancel(kind={kind!r}) takes no id: this cancel stops the running one; leave id out."
- )
- if kind == "training":
- if not id:
- status = await route_json("GET", "/api/train/status", caller = caller)
- id = opt_text(status.get("job_id")) if isinstance(status, dict) else None
- if not id or not (isinstance(status, dict) and status.get("is_training_running")):
- return CancelResult(
- kind = kind, cancelled = False, message = "No training job is running."
- )
- answer = await route_json(
- "POST",
- "/api/train/stop",
- caller = caller,
- json_body = {"save": save, "expected_job_id": id},
- )
- elif kind == "audio":
- between = stop_run(caller.account_id, id)
- if between:
- return done(True, f"The run stops before its next take; {KEPT_TAKES}")
- path, id_field = ROUTES[kind]
- answer = await route_json("POST", path, caller = caller, json_body = {id_field: id})
- if between is False:
- # The route stopped the take in flight, or it just ended; either way no take follows.
- return done(True, f"The run was stopped; {KEPT_TAKES}")
- elif kind == "export":
- if id:
- job = export_jobs.lookup(caller.account_id, id)
- if job.finished:
- return done(False, f"The export already {job.status}.")
- return done(*await _cancel_export_job(caller, job))
- status = await route_json("GET", EXPORT_STATUS, caller = caller)
- if not as_dict(status).get("is_export_active"):
- return done(False, "No export is running.")
- answer = await route_json("POST", "/api/export/cancel", caller = caller)
- if not _stopped(kind, answer):
- return done(False, _message(answer))
- return done(True, "The export was stopped and its checkpoint unloaded.")
- elif kind == "video" and id and video_queue.is_queue_id(id):
- return done(*video_queue.cancel(caller.account_id, id))
- elif kind == "model_download":
- stopped, state = await model_downloads.cancel_parts(caller, id)
- if stopped:
- return done(True, "Unsloth Studio is stopping the download.")
- return done(False, f"Nothing to stop: the download is {state or 'not found'}.")
- else:
- path, id_field = ROUTES[kind]
- answer = await route_json(
- "POST",
- path.format(id = quote(id or "", safe = "")),
- caller = caller,
- **({"json_body": {id_field: save if id_field == "save" else id}} if id_field else {}),
- )
- return done(_stopped(kind, answer), _message(answer))
+FACTS = {"cancel": {profile.STOPS_WORK}}
TOOLS = ((cancel, DESTRUCTIVE),)
diff --git a/studio/backend/studio_mcp/tools/data.py b/studio/backend/studio_mcp/tools/data.py
index 31f84b4fec6..88495d23a65 100644
--- a/studio/backend/studio_mcp/tools/data.py
+++ b/studio/backend/studio_mcp/tools/data.py
@@ -98,9 +98,9 @@ async def datasets(
"check_format" (``name``: a Hub repo id or a listed dataset's id): the detected format, columns and a suggested column mapping.
"download" (``repo_id``): start downloading a Hub dataset; "status" (``repo_id``): how that download is going.
"upload": save a .csv, .json, .jsonl or .parquet file sent as ``data_base64`` with its ``filename``, or ``rows`` as JSONL.
- Put a listed or uploaded dataset's ``ref`` in start_training's config.local_datasets.
+ <<start_training: Put a listed or uploaded dataset's ``ref`` in start_training's config.local_datasets.>>
"upload_images" (``name``, ``images``, optional ``captions``): add captioned images to the image dataset ``name``, creating it if needed.
- Pass that ``name`` as config.data_dir to start_training kind "diffusion".
+ <<start_training: Pass that ``name`` as config.data_dir to start_training kind "diffusion".>>
A ref lasts until Unsloth Studio restarts; after a restart, list or upload again for a new one.
``hf_token`` is for gated datasets."""
caller = current_caller()
diff --git a/studio/backend/studio_mcp/tools/export.py b/studio/backend/studio_mcp/tools/export.py
index 7a66aedcd7a..397fd7d09a4 100644
--- a/studio/backend/studio_mcp/tools/export.py
+++ b/studio/backend/studio_mcp/tools/export.py
@@ -11,6 +11,7 @@ from typing import Any, Literal, Optional, Union
from fastmcp.exceptions import ToolError
+from studio_mcp import profile
from studio_mcp import checkpoints, export_jobs
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import tool_error
@@ -115,4 +116,7 @@ async def export_model(
return ExportJobRef(job_id = job.job_id)
+# The export job keeps the key past the call and loads a checkpoint.
+FACTS = {"export_model": {profile.OUTLIVES_CALL, profile.SWAPS_MODELS}}
+
TOOLS = ((export_model, WRITES),)
diff --git a/studio/backend/studio_mcp/tools/images.py b/studio/backend/studio_mcp/tools/images.py
index df009c31b08..edf8e4950f8 100644
--- a/studio/backend/studio_mcp/tools/images.py
+++ b/studio/backend/studio_mcp/tools/images.py
@@ -29,8 +29,6 @@ from studio_mcp.media import (
from studio_mcp.outputs import ImageItem, ImageResult
from studio_mcp.tools import WRITES, integer, number, opt_text, present, route_json
-LOAD_IMAGE_HINT = "Load an image model with load_model(kind='image') first."
-NOT_LOADED = "No diffusion model is loaded"
# The route takes 128 MiB of base64 across every image in one request.
MAX_REQUEST_IMAGE_BYTES = 128 * 1024 * 1024 * 3 // 4
@@ -87,7 +85,6 @@ async def run_generation(
"/api/inference/images/generate",
caller = caller,
json_body = body,
- hint_if = (NOT_LOADED, {409: LOAD_IMAGE_HINT}),
)
payload = await loading.with_progress(ctx, generate, _progress_poll(caller))
rows = payload.get("images") if isinstance(payload, dict) else None
@@ -200,7 +197,7 @@ async def generate_image(
] = None,
ctx: Optional[Context] = None,
) -> ToolResult:
- """Generate or edit images with the image model loaded in Unsloth Studio (load_model(kind="image") first).
+ """Generate or edit images with the image model loaded in Unsloth Studio (<<load_model: load_model(kind="image") first | the user loads one on the Image page>>).
Each image is saved to the Unsloth Studio Images gallery and returned with its id and URL; images up to 1.5 MiB come back inline, larger ones as a 1024 px preview plus a link.
Width and height are pixels in multiples of studio_status image.dimension_multiple; left out, the size is 1024x1024 (an edit matches init_image).
Left out, steps and guidance come from the loaded model's defaults (studio_status image.generation_defaults).
diff --git a/studio/backend/studio_mcp/tools/jobs.py b/studio/backend/studio_mcp/tools/jobs.py
index d4877ea7c79..02c96597f34 100644
--- a/studio/backend/studio_mcp/tools/jobs.py
+++ b/studio/backend/studio_mcp/tools/jobs.py
@@ -5,332 +5,20 @@
from __future__ import annotations
-import asyncio
-import time
from typing import Annotated, Any, Literal, Optional
-from urllib.parse import quote
from fastmcp import Context
from fastmcp.exceptions import ToolError
from fastmcp.tools import ToolResult
from pydantic import Field
-from studio_mcp import checkpoints as named
-from studio_mcp import export_jobs, loading, model_downloads, video_queue
-from studio_mcp.caller import Caller, current_caller
-from studio_mcp.errors import raise_for_route
-from studio_mcp.forward import forward
-from studio_mcp.media import (
- INLINE_CAP,
- THUMB_SIDE,
- ReturnMedia,
- image_content,
- media_result,
- public_url,
- resource_link,
- signed_url,
- video_frame_path,
-)
-from studio_mcp.outputs import (
- ExportInfo,
- ExportJobSummary,
- JobStatus,
- JobSummary,
- RecipeError,
- RecipeInfo,
- RecipeResult,
- TrainingJob,
- VideoInfo,
-)
-from studio_mcp.tools import READ_ONLY, WRITES, as_dict, integer, leaf_name, number, opt_text
-from studio_mcp.tools import route_json
-from studio_mcp.tools.status import SLOT_ROUTES, _diffusion_training, _training
-
-
-def _video_path(video_id: str, suffix: str = "") -> str:
- return f"/v1/videos/{quote(video_id, safe = '')}{suffix}"
-
-
-async def _video_job(
- caller: Caller,
- video_id: str,
- return_media: ReturnMedia = "inline",
- preview_px: Optional[int] = None,
-) -> ToolResult:
- job = as_dict(await route_json("GET", _video_path(video_id), caller = caller))
- error = as_dict(job.get("error"))
- contents: list[Any] = []
- video = None
- if job.get("status") == "completed":
- # A picture at most: the MP4 can be hundreds of MB and is shared as a link.
- video_url = public_url(caller, _video_path(video_id, "/content"))
- download_url = await signed_url(caller, "video", video_id)
- thumb, mime = None, "image/webp"
- if return_media == "inline":
- thumb = await forward(
- caller, "GET", _video_path(video_id, "/content"), params = {"variant": "thumbnail"}
- )
- elif return_media == "preview":
- params = {"at": "first", "max_px": preview_px or THUMB_SIDE}
- thumb = await forward(caller, "GET", video_frame_path(video_id), params = params)
- mime = "image/png"
- inline = thumb is not None and thumb.status_code == 200 and len(thumb.content) <= INLINE_CAP
- if inline:
- contents.append(image_content(thumb.content, mime))
- contents.append(resource_link(download_url or video_url, f"{video_id}.mp4", "video/mp4"))
- video = VideoInfo(url = video_url, download_url = download_url, thumbnail_inline = inline)
- status = JobStatus(
- kind = "video",
- id = opt_text(job.get("id")) or video_id,
- status = "cancelled" if error.get("code") == "cancelled" else opt_text(job.get("status")),
- progress_percent = number(job.get("progress")),
- error = opt_text(error.get("message")),
- error_code = opt_text(error.get("code")),
- video = video,
- seed = integer(job.get("seed")),
- )
- return media_result(contents, status)
-
-
-async def _video_jobs(caller: Caller) -> ToolResult:
- listing = await route_json("GET", "/v1/videos", caller = caller)
- rows = as_dict(listing).get("data")
- jobs = [
- JobSummary.from_route(
- row,
- status = (
- "cancelled"
- if as_dict(row.get("error")).get("code") == "cancelled"
- else opt_text(row.get("status")) or "queued"
- ),
- progress_percent = number(row.get("progress")),
- )
- for row in rows or []
- if isinstance(row, dict) and opt_text(row.get("id"))
- ]
- return media_result([], JobStatus(kind = "video", jobs = jobs))
-
-
-RECIPE_ROUTES = "/api/data-recipe"
-
-
-def _recipe_dataset(artifact_path: Any) -> Optional[str]:
- leaf = leaf_name(artifact_path) if opt_text(artifact_path) else None
- return f"recipes/{leaf}" if leaf else None
-
-
-async def _recipe_job(
- caller: Caller, job_id: Optional[str], rows: Optional[int], offset: int
-) -> ToolResult:
- path = (
- f"{RECIPE_ROUTES}/jobs/{quote(job_id, safe = '')}/status"
- if job_id
- else f"{RECIPE_ROUTES}/jobs/current"
- )
- if job_id:
- job = await route_json("GET", path, caller = caller)
- else:
- response = await forward(caller, "GET", path)
- # No recipe has run since Unsloth Studio started: nothing to report, not an error.
- if response.status_code == 404:
- return media_result([], JobStatus(kind = "recipe", jobs = []))
- job = raise_for_route(response)
- job = as_dict(job)
- job_id = opt_text(job.get("job_id")) or job_id
- progress = as_dict(job.get("progress"))
- data_rows = total = None
- if rows and job_id:
- response = await forward(
- caller,
- "GET",
- f"{RECIPE_ROUTES}/jobs/{quote(job_id, safe = '')}/dataset",
- params = {"limit": rows, "offset": offset},
- )
- # 404 while no rows are written yet, 422 when the job ended without any (its detail names host
- # paths): the status still answers, without rows.
- page = None if response.status_code in (404, 422) else raise_for_route(response)
- if isinstance(page, dict):
- data_rows = [row for row in page.get("dataset") or [] if isinstance(row, dict)]
- total = integer(page.get("total"))
- status = JobStatus.from_route(
- job,
- kind = "recipe",
- id = job_id,
- progress_percent = number(progress.get("percent")),
- recipe = RecipeInfo.from_route(
- job,
- dataset = _recipe_dataset(job.get("artifact_path")),
- total_rows = total,
- data_rows = data_rows,
- ),
- )
- return media_result([], status)
-
-
-def _export_status(job: export_jobs.ExportJob) -> JobStatus:
- return JobStatus(
- kind = "export",
- id = job.job_id,
- status = job.status,
- error = job.error,
- export = ExportInfo(format = job.format, output = job.output, phase = job.phase),
- )
-
-
-async def _export_job(caller: Caller, job_id: Optional[str]) -> ToolResult:
- if job_id is None:
- jobs = [
- ExportJobSummary(
- id = job.job_id,
- status = job.status,
- format = job.format,
- phase = job.phase,
- output = job.output,
- error = job.error,
- )
- for job in reversed(export_jobs.jobs_of(caller.account_id))
- ]
- return media_result([], JobStatus(kind = "export", jobs = jobs))
- # Settles from its own export call, not the export status (that is whichever op ran last).
- return media_result([], _export_status(export_jobs.lookup(caller.account_id, job_id)))
-
-
-# Training phases by job status; any other phase means the run is still going.
-TRAINING_STATUS = {
- "completed": "completed",
- "error": "failed",
- "stopped": "cancelled",
- "idle": "idle",
-}
-
-
-async def _training_job(caller: Caller, kind: str, job_id: Optional[str]) -> ToolResult:
- payload = as_dict(await route_json("GET", SLOT_ROUTES[kind], caller = caller))
- slot = (_training if kind == "training" else _diffusion_training)(payload)
- # An id that is not the current job (or one with nothing running) is never echoed back as idle.
- if job_id and job_id != slot.job_id:
- # list_training_runs reads LLM runs only.
- where = (
- f'; list_training_runs(run_id="{job_id}") has its result' if kind == "training" else ""
- )
- raise ToolError(f"{job_id} is not the current training job{where}")
- phase = "running" if kind == "diffusion_training" and slot.phase == "busy" else slot.phase
- status = TRAINING_STATUS.get(phase, "running")
- training = TrainingJob(**slot.model_dump())
- if status == "completed":
- details = as_dict(payload.get("details")) if kind == "training" else payload
- run, found = await _run_folder(caller, opt_text(details.get("output_dir")))
- training = training.model_copy(
- update = {
- "run_folder": run,
- "checkpoints": [c.name for c in found if run and c.run == run],
- # list_training_runs reads LLM runs only.
- "loss_history": (
- f'list_training_runs(run_id="{slot.job_id}")'
- if kind == "training" and slot.job_id
- else None
- ),
- }
- )
- return media_result(
- [],
- JobStatus(
- kind = kind,
- id = slot.job_id or job_id,
- status = status,
- progress_percent = slot.progress_percent,
- error = slot.error,
- training = training,
- ),
- )
-
-
-async def _run_folder(caller: Caller, output: Optional[str]) -> tuple[Optional[str], list]:
- """The run folder name for a status ``output_dir``: an API key gets an opaque reference, matched like list_training_runs does."""
- from hub.utils.host_paths import cache_reference
-
- found, folders = await named.list_checkpoints(caller)
- if not output:
- return None, found
- for folder, path in folders.items():
- if output in (path, cache_reference(path)):
- return folder, found
- return (None if output.startswith("ref:") else leaf_name(output)), found
-
-
-def _load_status(job: loading.LoadJob) -> JobStatus:
- return JobStatus(
- kind = "load",
- id = job.job_id,
- status = job.status,
- progress_percent = (
- 100.0
- if job.status == "completed"
- else round(100.0 * job.fraction, 1)
- if job.fraction is not None
- else None
- ),
- error = job.error,
- load = job.result if job.status == "completed" else None,
- )
-
-
-async def _load_job(caller: Caller, job_id: Optional[str]) -> ToolResult:
- if job_id is None:
- jobs = [
- JobSummary(id = job.job_id, status = job.status)
- for job in loading.LOADS.jobs_of(caller.account_id)
- ]
- return media_result([], JobStatus(kind = "load", jobs = jobs))
- return media_result([], _load_status(loading.LOADS.lookup(caller.account_id, job_id)))
-
-
-async def _read_once(
- caller: Caller,
- kind: str,
- job_id: Optional[str],
- rows: Optional[int],
- offset: int,
- return_media: ReturnMedia = "inline",
- preview_px: Optional[int] = None,
-) -> ToolResult:
- if kind == "recipe":
- return await _recipe_job(caller, job_id, rows, offset)
- if kind == "export":
- return await _export_job(caller, job_id)
- if kind == "load":
- return await _load_job(caller, job_id)
- if kind in ("training", "diffusion_training"):
- return await _training_job(caller, kind, job_id)
- if kind == "download":
- if not job_id:
- raise ToolError('get_job(kind="download") needs id: the id download_model returned.')
- return media_result([], await model_downloads.status(caller, job_id))
- if job_id is None:
- return await _video_jobs(caller)
- if video_queue.is_queue_id(job_id):
- item = video_queue.lookup(caller.account_id, job_id)
- if not item.video_id:
- queued = await video_queue.job_status(item)
- # Unless it started while that was read: then it is the video it became.
- if not item.video_id:
- return media_result([], queued)
- return await _video_job(caller, item.video_id, return_media, preview_px)
- return await _video_job(caller, job_id, return_media, preview_px)
-
-
-# The least time get_job gives its first read and, at the end of a wait, its rows read.
-FIRST_READ_S = 30
-LAST_READ_S = 5
-# Job statuses that mean the job is still going; get_job(wait_s) waits only on these.
-RUNNING = {"running", "queued", "in_progress", "created", "pending", "active", "cancelling"}
-
-
-def _moment(structured: Any) -> tuple[Any, Any, Any]:
- # (status, phase, percent): a wait ends when the first two change. Export has no percent, only a phase.
- job = as_dict(structured)
- phase = as_dict(job.get("export")).get("phase") or as_dict(job.get("training")).get("phase")
- return job.get("status"), phase, job.get("progress_percent")
+from studio_mcp import profile
+from studio_mcp import jobs, loading
+from studio_mcp.caller import current_caller
+from studio_mcp.job_kinds import RECIPE_ROUTES
+from studio_mcp.media import ReturnMedia
+from studio_mcp.outputs import JobStatus, RecipeError, RecipeResult
+from studio_mcp.tools import READ_ONLY, WRITES, as_dict, opt_text, route_json
async def get_job(
@@ -369,81 +57,21 @@ async def get_job(
kind "video": with ``id``, its status and progress, and once completed a thumbnail plus the video's URL; without ``id``, recent video jobs.
kind "recipe": a data recipe job's status and progress (without ``id``, the current one), and with ``rows`` that many generated rows from ``offset``.
Unsloth Studio runs one recipe at a time; a recipe job id is not tied to an account.
- kind "export": an export_model job by its id (without ``id``, this key's export jobs), with its output named relative to Unsloth Studio's exports folder.
- kind "training" or "diffusion_training": the current run started by start_training (``id`` is its job id), and once completed its run folder and checkpoint names; ``loss_history`` names the list_training_runs call with the full loss curve.
- kind "load": a load_model call that returned ``status`` "loading", by its ``job_id``; once completed, ``load`` is the load's result with what it unloaded.
+ kind "export": an <<export_model: export_model | export>> job by its id (without ``id``, this key's export jobs), with its output named relative to Unsloth Studio's exports folder.
+ kind "training" or "diffusion_training": the current run<<start_training: started by start_training>> (``id`` is its job id), and once completed its run folder and checkpoint names; ``loss_history`` names the list_training_runs call with the full loss curve.
+ kind "load": a <<load_model: load_model call | load>> that returned ``status`` "loading", by its ``job_id``; once completed, ``load`` is the load's result with what it unloaded.
kind "download": a download_model download by the id it returned."""
- caller = current_caller()
- deadline = time.monotonic() + min(wait_s, loading.MAX_WAIT_S)
- # Forwarded reads have no HTTP timeout, so each one here is bounded: the first by the wait (at
- # least FIRST_READ_S), the polls and the final rows read by what is left of it.
- first = max(min(wait_s, loading.MAX_WAIT_S), FIRST_READ_S)
- try:
- result = await asyncio.wait_for(
- _read_once(caller, kind, id, rows, offset, return_media, preview_px), timeout = first
- )
- except asyncio.TimeoutError:
- raise ToolError(
- f"Unsloth Studio did not report on the {kind} job within {first:g} s; call get_job again"
- ) from None
- start = _moment(result.structured_content)
- # A listing has nothing to wait on.
- waits = id is not None or kind in ("recipe", "training", "diffusion_training")
- moved = polled = False
- while waits and start[0] in RUNNING:
- left = deadline - time.monotonic()
- if left <= 0:
- break
- await asyncio.sleep(min(loading.POLL_INTERVAL_S, left))
- try:
- # Recipe rows are read once, for the answer, not on every poll; a read that stalls past
- # the deadline ends the wait with the last answer.
- latest = await asyncio.wait_for(
- _read_once(caller, kind, id, None, offset, return_media, preview_px),
- timeout = max(deadline - time.monotonic(), 0.01),
- )
- except asyncio.TimeoutError:
- break
- except Exception:
- # Like a load's progress poll: a failed read during the wait is skipped.
- continue
- result, polled = latest, True
- now = _moment(result.structured_content)
- if now[:2] != start[:2]:
- moved = True
- break
- if ctx is not None and now[2] is not None:
- await ctx.report_progress(min(now[2] / 100.0, 1.0), 1.0, str(now[1] or now[0]))
- if polled and rows:
- try:
- result = await asyncio.wait_for(
- _read_once(caller, kind, id, rows, offset, return_media, preview_px),
- timeout = max(deadline - time.monotonic(), LAST_READ_S),
- )
- except asyncio.TimeoutError:
- pass # The answer goes out without rows; the next get_job reads them.
- # A wait that ended because the job moved on can be followed again at once.
- return _with_poll_after(kind, result, 0 if moved else POLL_AFTER_S[kind])
-
-
-# Seconds a caller not using wait_s should leave before asking again, by kind.
-POLL_AFTER_S = {
- "video": 15,
- "recipe": 10,
- "export": 15,
- "training": 30,
- "diffusion_training": 30,
- "load": 10,
- "download": 15,
-}
-
-
-def _with_poll_after(kind: str, result: ToolResult, after: float) -> ToolResult:
- structured = as_dict(result.structured_content)
- if structured.get("status") not in RUNNING or structured.get("jobs") is not None:
- return result
- status = JobStatus.model_validate({**structured, "poll_after_s": after})
- return media_result(list(result.content[1:]), status)
+ return await jobs.follow(
+ current_caller(),
+ kind,
+ id,
+ wait_s = wait_s,
+ ctx = ctx,
+ rows = rows,
+ offset = offset,
+ return_media = return_media,
+ preview_px = preview_px,
+ )
async def run_recipe(
@@ -472,4 +100,7 @@ async def run_recipe(
return RecipeResult(mode = mode, job_id = job_id)
+# A recipe can send host env credentials and host files to the provider endpoint it names.
+FACTS = {"run_recipe": {profile.SENDS_HOST_SECRETS}}
+
TOOLS = ((run_recipe, WRITES), (get_job, READ_ONLY, JobStatus.model_json_schema()))
diff --git a/studio/backend/studio_mcp/tools/models.py b/studio/backend/studio_mcp/tools/models.py
index 6a4940a33ad..8ffc8f0bc9b 100644
--- a/studio/backend/studio_mcp/tools/models.py
+++ b/studio/backend/studio_mcp/tools/models.py
@@ -14,6 +14,7 @@ from fastmcp.exceptions import ToolError
from fastmcp.tools import ToolResult
from pydantic import Field
+from studio_mcp import profile
from studio_mcp import loading, model_downloads, placement, trained_models
from studio_mcp.caller import current_caller
from studio_mcp.media import media_result
@@ -288,14 +289,14 @@ async def list_models(
] = "local",
) -> ModelList:
"""Models this Unsloth Studio can serve: loaded ones and those already downloaded.
- Each entry has the id to pass to load_model, its kind and whether it is loaded.
- ``kind`` is read from the model's task; a model with no task is reported as "llm", which also covers embedding models and unloaded text-to-speech models Unsloth Studio cannot classify yet, so pass the kind explicitly to load_model.
+ Each entry has the id to pass <<load_model: to load_model | as a generate tool's ``model``>>, its kind and whether it is loaded.
+ ``kind`` is read from the model's task; a model with no task is reported as "llm", which also covers embedding models and unloaded text-to-speech models Unsloth Studio cannot classify yet<<load_model: , so pass the kind explicitly to load_model>>.
``loaded_only`` returns just the resident models.
``model`` narrows the list to that model (empty when it is not downloaded yet) and adds Unsloth Studio's training defaults for it, which also works for a Hugging Face repo id that is not downloaded (send X-Unsloth-HF-Token for a gated repo).
``workflow`` keeps only audio models that run that Unsloth Studio Audio page (their ``audio_workflows``), such as the ids to pass to generate_audio as ``model``.
With source="catalog" it lists image, video and audio models Unsloth Studio can download, with size_bytes (decimal), low_vram and fits_now (whether it fits in the free memory of one GPU right now; null when unknown).
LLM rows are not in the catalog: list downloaded LLMs with the default source, or load a Hugging Face id.
- Load a catalog row with load_model(model=id, kind=its kind).
+ <<load_model: Load a catalog row with load_model(model=id, kind=its kind).>>
"""
if source == "catalog":
models = await _catalog(kind, loaded_only, workflow)
@@ -560,13 +561,13 @@ async def download_model(
h3_task: H3Task = None,
ctx: Optional[Context] = None,
) -> DownloadRef:
- """Download a model ahead of time without loading it, so a later load_model starts sooner.
+ """Download a model ahead of time without loading it, so a later load starts sooner.
The download keeps running in Unsloth Studio's download manager after this returns.
- ``kind`` is the kind load_model takes: "llm", "tts" and "audio" fetch the repo (for a GGUF repo only ``variant``, by default the recommended one), "image" and "video" the files their load reads, and "stt" a speech-to-text model.
- Follow it with get_job(kind="download", id=<the returned id>) and stop it with cancel(kind="model_download", id=<the same id>).
+ ``kind`` is the kind <<load_model: load_model takes | list_models reports>>: "llm", "tts" and "audio" fetch the repo (for a GGUF repo only ``variant``, by default the recommended one), "image" and "video" the files their load reads, and "stt" a speech-to-text model.
+ Follow it with get_job(kind="download", id=<the returned id>)<<cancel: and stop it with cancel(kind="model_download", id=<the same id>)>>.
A speech-to-text download finishes before this returns, so it has no id.
- load_model waits for a running download of the same model.
- ``hf_token`` is for gated repos. For image and video, pass the options the later load_model will take: they pick the files it reads, such as a pre-cast text encoder."""
+ <<load_model: load_model waits for a running download of the same model.>>
+ ``hf_token`` is for gated repos. For image and video, pass the options the later load will take: they pick the files it reads, such as a pre-cast text encoder."""
knobs = placement.media_knobs(
kind,
memory_mode = memory_mode,
@@ -586,6 +587,12 @@ async def download_model(
)
+FACTS = {
+ "load_model": {profile.SWAPS_MODELS},
+ "unload_model": {profile.SWAPS_MODELS},
+ "plan_load": {profile.PREVIEWS_SWAPS},
+}
+
TOOLS = (
(list_models, READ_ONLY),
(load_model, WRITES),
diff --git a/studio/backend/studio_mcp/tools/status.py b/studio/backend/studio_mcp/tools/status.py
index 6f10c64feaf..8ed96eb41db 100644
--- a/studio/backend/studio_mcp/tools/status.py
+++ b/studio/backend/studio_mcp/tools/status.py
@@ -219,7 +219,7 @@ async def _generating(caller: Caller, slot: str) -> bool:
async def studio_status() -> StudioStatus:
- """What Unsloth Studio is doing right now: the loaded chat, image, video, speech-to-text and embedding models, any model still loading or downloading, whether an image or video is generating, the LLM and image (diffusion) training jobs, the export job and GPU use. A loaded audio model lists its ``audio_options`` for generate_audio, such as its built-in voices. Call this before loading a model or starting GPU work. The embedding model is managed by Unsloth Studio and unload_model does not unload it. A slot that could not be read is listed under ``unavailable`` with the reason."""
+ """What Unsloth Studio is doing right now: the loaded chat, image, video, speech-to-text and embedding models, any model still loading or downloading, whether an image or video is generating, the LLM and image (diffusion) training jobs, the export job and GPU use. A loaded audio model lists its ``audio_options`` for generate_audio, such as its built-in voices. Call this before loading a model or starting GPU work. The embedding model is managed by Unsloth Studio<<unload_model: and unload_model does not unload it>>. A slot that could not be read is listed under ``unavailable`` with the reason."""
caller = current_caller()
slots = list(SLOT_ROUTES)
results, generating = await asyncio.gather(
diff --git a/studio/backend/studio_mcp/tools/text.py b/studio/backend/studio_mcp/tools/text.py
index 57ab9964699..0a6958a8641 100644
--- a/studio/backend/studio_mcp/tools/text.py
+++ b/studio/backend/studio_mcp/tools/text.py
@@ -15,6 +15,7 @@ from fastmcp.exceptions import ToolError
from pydantic import BaseModel, ConfigDict, Field
from state.tool_policy import tools_force_disabled
+from studio_mcp import profile
from studio_mcp.caller import current_caller
from studio_mcp.errors import raise_for_route
from studio_mcp.forward import forward
@@ -32,8 +33,6 @@ from studio_mcp.tools import READ_ONLY, WRITES, integer, number, opt_text, prese
MAX_EMBED_INPUTS = 2048
DEFAULT_TOP_K = 10
-LOAD_CHAT_HINT = "Load a chat model with load_model first; list_models shows the downloaded ones."
-NOT_LOADED = "No model loaded"
# The chat route takes 128 MiB of base64 images per request.
MAX_CHAT_IMAGE_BYTES = 128 * 1024 * 1024 * 3 // 4
EMBED_DOWNLOAD_HINT = (
@@ -146,12 +145,7 @@ async def chat(
}
# Beats a CLI --enable-tools too; forward's task copies this context into the route.
with tools_force_disabled():
- payload = await route_json(
- "POST",
- "/v1/chat/completions",
- json_body = body,
- hint_if = (NOT_LOADED, {400: LOAD_CHAT_HINT}),
- )
+ payload = await route_json("POST", "/v1/chat/completions", json_body = body)
choices = payload.get("choices") if isinstance(payload, dict) else None
if not isinstance(choices, list) or not choices or not isinstance(choices[0], dict):
raise ToolError("Unsloth Studio returned no reply")
@@ -321,4 +315,6 @@ async def system_one(
)
+FACTS = {"chat": {profile.REENTERS_CHAT}}
+
TOOLS = ((chat, WRITES), (embed, READ_ONLY), (system_one, READ_ONLY))
diff --git a/studio/backend/studio_mcp/tools/training.py b/studio/backend/studio_mcp/tools/training.py
index 19926ba0c94..377f4590ba1 100644
--- a/studio/backend/studio_mcp/tools/training.py
+++ b/studio/backend/studio_mcp/tools/training.py
@@ -13,6 +13,7 @@ from urllib.parse import quote
from fastmcp.exceptions import ToolError
+from studio_mcp import profile
from studio_mcp import checkpoints as named
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import raise_for_status_field
@@ -308,7 +309,7 @@ async def list_training_runs(
limit: int = 50,
offset: int = 0,
) -> TrainingRuns:
- """Training runs, newest first, with each run's folder; with ``run_id``, that run's saved settings and loss curve too. ``include_checkpoints`` lists every checkpoint by the name export_model takes: "<run folder>" for the final weights or "<run folder>/checkpoint-N". ``limit`` is 1 to 200."""
+ """Training runs, newest first, with each run's folder; with ``run_id``, that run's saved settings and loss curve too. ``include_checkpoints`` lists every checkpoint by the name <<export_model: export_model takes | Unsloth Studio exports it under>>: "<run folder>" for the final weights or "<run folder>/checkpoint-N". ``limit`` is 1 to 200."""
caller = current_caller()
checkpoints, folders_by_ref = await _folders_by_ref(caller)
limit, offset = max(1, min(limit, 200)), max(0, offset)
@@ -349,4 +350,7 @@ async def list_training_runs(
)
+# A run outlives the call that started it and keeps using its key.
+FACTS = {"start_training": {profile.OUTLIVES_CALL}}
+
TOOLS = ((start_training, WRITES), (list_training_runs, READ_ONLY))
diff --git a/studio/backend/studio_mcp/tools/video.py b/studio/backend/studio_mcp/tools/video.py
index 27ee8c580f1..38cd8b8046b 100644
--- a/studio/backend/studio_mcp/tools/video.py
+++ b/studio/backend/studio_mcp/tools/video.py
@@ -29,7 +29,6 @@ from utils.upload_limits import (
VIDEO_INPUT_REFERENCE_MAX_BYTES,
)
-LOAD_VIDEO_HINT = "Load a video model with load_model(kind='video') first."
# /v1/videos takes a reference audio of at most 24 MB.
MAX_REFERENCE_AUDIO_BYTES = 24 * 1024 * 1024
# /v1/videos takes at most this many frames (MAX_VIDEO_NUM_FRAMES).
@@ -44,7 +43,7 @@ TOO_MANY_IMAGE_BYTES = (
def _refuse_large_audio(caller: Any, audio: AudioInput) -> None:
"""Refuse audio over the video cap before audio_ref reads and stores it."""
size = None
- if audio.path is not None and caller.direct_local:
+ if audio.path is not None and caller.reads_host_files:
try:
size = Path(audio.path).expanduser().stat().st_size
except OSError:
@@ -122,7 +121,7 @@ async def generate_video(
Field(ge = 1, le = 120, description = "Playback frame rate; left out, the model's default."),
] = None,
) -> VideoJobRef:
- """Start a video with the video model loaded in Unsloth Studio (load_model(kind="video") first) and return its job at once.
+ """Start a video with the video model loaded in Unsloth Studio (<<load_model: load_model(kind="video") first | the user loads one on the Video page, or name one in ``model``>>) and return its job at once.
Poll get_job(kind="video", id=...) until it is completed, which returns a thumbnail and the video's URL.
Unsloth Studio renders one video at a time: while one runs, another call is refused with HTTP 409, so wait for the first to finish.
``seconds`` is a number or a string and ``size`` is "WIDTHxHEIGHT" from studio_status video.size_presets; leave them out to use the model's defaults.
@@ -189,7 +188,7 @@ async def generate_video(
raise ToolError(TOO_MANY_IMAGE_BYTES)
if reference_audios:
body["reference_audios"] = [await audio_ref(caller, audio) for audio in reference_audios]
- job = await video_queue.post_or_queue(caller, body, hints = {503: LOAD_VIDEO_HINT})
+ job = await video_queue.post_or_queue(caller, body)
return job if isinstance(job, VideoJobRef) else job_ref(job)
diff --git a/studio/backend/studio_mcp/video_queue.py b/studio/backend/studio_mcp/video_queue.py
index 2918b435a85..1567ae1fbc1 100644
--- a/studio/backend/studio_mcp/video_queue.py
+++ b/studio/backend/studio_mcp/video_queue.py
@@ -19,7 +19,7 @@ import httpx
from fastmcp.exceptions import ToolError
from studio_mcp.caller import Caller
-from studio_mcp.errors import raise_for_route
+from studio_mcp.errors import raise_for_route, tool_error
from studio_mcp.forward import forward, parse_json
from studio_mcp.outputs import JobStatus, VideoJobRef
from studio_mcp.tools import as_dict, number, opt_text, try_json
@@ -271,6 +271,12 @@ async def _admit(caller: Caller, body: dict, hints: Optional[dict]) -> Union[dic
if video_id:
_running[caller.account_id] = (video_id, time.monotonic())
return job
+ if caller.call_scoped:
+ # A queued clip is posted later with this caller's token, which is revoked when this call returns.
+ raise tool_error(
+ "Unsloth Studio is making another video, so this one was not started. Try again once it finishes.",
+ tag = "gpu_busy",
+ )
item = _enqueue(caller, body, hints)
_ensure_pump(caller.account_id)
position, eta = await _position_eta(item)
diff --git a/studio/backend/tests/data/refactor_guard/ast_inventory.json b/studio/backend/tests/data/refactor_guard/ast_inventory.json
index 83e0bfce8aa..a1eabd7e276 100644
--- a/studio/backend/tests/data/refactor_guard/ast_inventory.json
+++ b/studio/backend/tests/data/refactor_guard/ast_inventory.json
@@ -1237,9 +1237,6 @@
"BUDGET_EXHAUSTED_NUDGE": {
"kind": "assign"
},
- "DUPLICATE_CALL_NUDGE": {
- "kind": "assign"
- },
"INTENT_SIGNAL": {
"kind": "assign"
},
diff --git a/studio/backend/tests/data/refactor_guard/runtime_inventory.json b/studio/backend/tests/data/refactor_guard/runtime_inventory.json
index 9ab2cd235b8..4f7fe8981eb 100644
--- a/studio/backend/tests/data/refactor_guard/runtime_inventory.json
+++ b/studio/backend/tests/data/refactor_guard/runtime_inventory.json
@@ -3,7 +3,6 @@
"dir": [
"Any",
"BUDGET_EXHAUSTED_NUDGE",
- "DUPLICATE_CALL_NUDGE",
"INTENT_SIGNAL",
"MAX_ACT_REPROMPTS",
"NUDGE_TOOL_CALLS_STATUS",
diff --git a/studio/backend/tests/test_audio_run_cancel.py b/studio/backend/tests/test_audio_run_cancel.py
index d39a1b2b965..0d428fbcdf6 100644
--- a/studio/backend/tests/test_audio_run_cancel.py
+++ b/studio/backend/tests/test_audio_run_cancel.py
@@ -84,6 +84,27 @@ def test_cancel_by_id_stops_only_that_run(use_backend):
assert done_b.status_code == 200 and len(done_b.json()["clips"]) == 1
+def test_stopping_the_callers_generation_ticket_stops_the_run(use_backend):
+ from core.inference.generation_ticket import GenerationTicket, generation_ticket
+
+ backend, started, release = _blocking_backend()
+ use_backend(backend)
+
+ async def scenario():
+ transport = httpx.ASGITransport(app = app_for(ALICE))
+ async with httpx.AsyncClient(transport = transport, base_url = "http://t") as client:
+ body = {"workflow": "speak", "text": RUN_A, "cancel_id": RUN_A}
+ with generation_ticket(ticket := GenerationTicket()):
+ run = asyncio.create_task(client.post("/api/inference/audio/run", json = body))
+ assert await asyncio.to_thread(started[RUN_A].wait, 10) and ticket.stop() is True
+ try:
+ return await asyncio.wait_for(asyncio.shield(run), 10)
+ finally:
+ release.set()
+
+ assert asyncio.run(scenario()).status_code == 499
+
+
def test_an_early_cancel_is_kept_for_the_run_that_follows(use_backend):
backend, started, _release = _blocking_backend()
use_backend(backend)
diff --git a/studio/backend/tests/test_gpu_arbiter.py b/studio/backend/tests/test_gpu_arbiter.py
index c52b70cf0f5..767ad441cd1 100644
--- a/studio/backend/tests/test_gpu_arbiter.py
+++ b/studio/backend/tests/test_gpu_arbiter.py
@@ -847,6 +847,7 @@ def test_always_refuses_instead_of_evicting(arb_log, monkeypatch, resident, owne
assert arb.residents() == {resident: None}
http = excinfo.value.as_http_exception("/api/inference/load")
+ assert http.headers.pop("X-Unsloth-Problem") == f"multi_model_always kind={kind}"
assert http.status_code == 409 and http.headers == {"X-Unsloth-Refusal": "multi-model-always"}
assert isinstance(http.detail, str) and "is set to Always" in http.detail
v1 = excinfo.value.as_http_exception("/v1/chat/completions")
diff --git a/studio/backend/tests/test_inference_model_identity.py b/studio/backend/tests/test_inference_model_identity.py
new file mode 100644
index 00000000000..44ece4255b9
--- /dev/null
+++ b/studio/backend/tests/test_inference_model_identity.py
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import os
+
+import pytest
+
+from core.inference import model_identity as mi
+from studio_mcp import loading, model_downloads, placement
+from studio_mcp.outputs import SlotModel
+
+AUDIO = "audio-cpp/audio.cpp-gguf/Qwen3-TTS"
+NT = os.name == "nt"
+
+
+ "name, local, split",
+ [
+ ("unsloth/Qwen3-GGUF:Q4_K_M", False, ("unsloth/Qwen3-GGUF", "Q4_K_M")),
+ ("unsloth/Qwen3-GGUF:", False, ("unsloth/Qwen3-GGUF", None)),
+ (f"{AUDIO}:Q8_0", False, (AUDIO, "Q8_0")),
+ ("org/repo:sub/dir", False, ("org/repo:sub/dir", None)),
+ ("ab:x", False, ("ab", "x")),
+ ("1:x", False, ("1", "x")),
+ ("~/m/a.gguf", True, ("~/m/a.gguf", None)),
+ ("C:\\models\\a.gguf", True, ("C:\\models\\a.gguf", None)),
+ ("C:/models/a.gguf", True, ("C:/models/a.gguf", None)),
+ ("C:x", True, ("C:x", None)),
+ ("m\\a.gguf", True, ("m\\a.gguf", None)),
+ ("ref:0123abcd", True, ("ref:0123abcd", None)),
+ ],
+)
+def test_names(monkeypatch, name, local, split):
+ assert mi.is_local(name) is placement.is_local(name) is local
+ assert model_downloads._looks_local(name) is local
+ assert mi.split_variant(name) == split
+ if local or split[1]:
+ assert placement._split(name, None) == model_downloads._split(name, None) == split
+ asked = []
+
+ async def route_json(method, path, **kwargs):
+ asked.append(path)
+ return {}
+
+ monkeypatch.setattr(loading, "route_json", route_json)
+ asyncio.run(loading._llm_poll(None, name)())
+ # Only a Hub name has download progress to read.
+ assert ("/api/models/download-progress" in asked) is not local
+
+
+ "left, right, model, repo",
+ [
+ ("unsloth/Qwen3-0.6B-GGUF", "UNSLOTH/qwen3-0.6b-gguf", True, True),
+ (" unsloth/Qwen3 ", "unsloth/qwen3", True, True),
+ ("unsloth/Qwen3-GGUF:Q4_K_M", "unsloth/qwen3-gguf", False, True),
+ ("unsloth/Qwen3-GGUF:q4_k_m", "unsloth/Qwen3-GGUF:Q4_K_M", True, True),
+ ("org/repo:Q4_K_M-3.97bpw", "org/repo:Q4_K_M-4.19bpw", False, True),
+ ("unsloth/Qwen3-GGUF", "unsloth/Gemma-GGUF", False, False),
+ (AUDIO, AUDIO.lower(), True, True),
+ ("/models/Foo.gguf", "/models/foo.gguf", NT, NT),
+ ("/models/Foo/", "/models/Foo", True, True),
+ ("./m/Foo", "./m/foo", NT, NT),
+ ("C:\\models\\a.gguf", "C:/models/a.gguf", True, True),
+ ("C:\\models\\a.gguf", "C:\\models\\b.gguf", False, False),
+ ("/models/a:b.gguf", "/models/a:c.gguf", False, False),
+ ("ref:ABC", "ref:ABC", True, True),
+ ("ref:ABC", "ref:abc", NT, NT),
+ (None, "unsloth/Qwen3", False, False),
+ ],
+)
+def test_same_model_and_repo(left, right, model, repo):
+ for a, b in ((left, right), (right, left)):
+ assert mi.same_model(a, b) is mi.matches_any(a, (None, "", b)) is model
+ assert mi.same_repo(a, b) is repo
+
+
+ "variant, filename, settled, result",
+ [
+ ("Q4_K_M", "model-Q4_K_M.gguf", True, True),
+ ("q4_k_m", "model-Q4_K_M.gguf", False, True),
+ ("Q8_0", "model-Q4_K_M.gguf", True, False),
+ # Status drops the bpw suffix: mid-load a sibling build cannot be told apart.
+ ("IQ4_XS", "model-IQ4_XS-3.97bpw.gguf", True, True),
+ ("IQ4_XS", "model-IQ4_XS-3.97bpw.gguf", False, False),
+ ("Q4_K_M", "model.safetensors", True, None),
+ ],
+)
+def test_resident_quant_matches(variant, filename, settled, result):
+ assert mi.resident_quant_matches(variant, filename, settled = settled) is result
+
+
+def models_dir(tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ (tmp_path / "models").mkdir()
+ (tmp_path / "models" / "Foo.gguf").write_bytes(b"")
+
+
+def _predict(
+ kind,
+ model,
+ resident,
+ mode = "always",
+):
+ slots = [SlotModel(kind = kind, model = resident)]
+ args = dict(device = None, alongside = None, mode = mode, status = {}, slots = slots)
+ return placement.predict(kind = kind, model = model, **args)
+
+
+ "left, right",
+ [
+ ("models/Foo.gguf", "models/foo.gguf"),
+ ("unsloth/Qwen3-GGUF:Q4_K_M", "UNSLOTH/qwen3-gguf"),
+ ("/m/Foo", "/m/foo"),
+ ("C:\\m\\a.gguf", "C:\\m\\b.gguf"),
+ (AUDIO, AUDIO.upper()),
+ ("org/repo:sub/dir", "org/repo"),
+ ],
+)
+def test_load_and_plan_agree(models_dir, left, right):
+ assert _predict("llm", left, right)[2] is not loading._same_id(left, right)
+
+
+def test_an_existing_relative_path_keeps_its_case(models_dir):
+ assert mi.is_local("models/Foo.gguf", probe = True) and not mi.is_local("models/Foo.gguf")
+ assert not mi.is_local("unsloth/Qwen3", probe = True)
+ assert mi.same_model("models/foo.gguf", "models/Foo.gguf", probe = True) is NT
+ assert mi.same_model("models/Foo.gguf", "models/foo.gguf")
+ others, exact, _ = _predict("stt", "models/Foo.gguf", "models/foo.gguf", mode = None)
+ # Windows reads them as one file; elsewhere they are two.
+ assert NT or ([s.model for s in others], exact) == (["models/foo.gguf"], False)
+ assert model_downloads.keys_for(None, "llm", "~/m/a.gguf", None) == []
+
+
+def test_route_and_status_keep_their_old_rules():
+ import routes.inference as route
+
+ # Not vouched for as a path there: a dot-relative or forward-slash drive name.
+ for name in ("/m", "~/m", "m\\a", "./m", "C:/m", "o/r"):
+ assert route._looks_like_local_path(name) is (name in ("/m", "~/m", "m\\a")), name
+ # Status may spell the resident path differently from the request.
+ assert loading._resident_matches({"loaded": True, "repo_id": "/m/foo"}, "/m/Foo")
+ assert not loading._resident_matches({"loaded": True, "repo_id": "/m/bar"}, "/m/Foo")
diff --git a/studio/backend/tests/test_llama_cpp_tool_loop.py b/studio/backend/tests/test_llama_cpp_tool_loop.py
index ce8f38ca4fb..4917d933813 100644
--- a/studio/backend/tests/test_llama_cpp_tool_loop.py
+++ b/studio/backend/tests/test_llama_cpp_tool_loop.py
@@ -5455,6 +5455,35 @@ def test_gguf_textual_fallback_collapses_duplicate_tool_calls(monkeypatch):
assert len(calls) == 1, [c[0] for c in calls]
+def test_gguf_textual_fallback_keeps_two_identical_unseeded_studio_generations(monkeypatch):
+ from core.inference import tool_facts
+
+ name = "mcp__unsloth__generate_image"
+ tool_facts.note_mcp_tool(name, {"name": "generate_image"}, studio = True)
+ blocks = '<tool_call>{"name":"%s","arguments":{"prompt":"a cat"}}</tool_call>' % name * 2
+ first_stream = [_sse({"content": blocks}), _done()]
+ final_stream = [_sse({"content": "done"}), _done()]
+ backend, _payloads = _backend_and_payloads(monkeypatch, [first_stream, final_stream])
+
+ calls: list[tuple[str, dict]] = []
+ monkeypatch.setattr(
+ "core.inference.tools.execute_tool",
+ lambda name, arguments, **_k: calls.append((name, arguments)) or "OK",
+ )
+ try:
+ list(
+ backend.generate_chat_completion_with_tools(
+ messages = [{"role": "user", "content": "two cats"}],
+ tools = [{"type": "function", "function": {"name": name}}],
+ max_tool_iterations = 1,
+ )
+ )
+ finally:
+ tool_facts.note_mcp_tool(name, {"name": "generate_image"})
+
+ assert calls == [(name, {"prompt": "a cat"})] * 2
+
+
@pytest.mark.parametrize("deduplicate", [True, False])
def test_gguf_textual_fallback_keeps_identical_calls_when_deduplication_is_off(
monkeypatch, deduplicate
@@ -7402,3 +7431,20 @@ def test_appended_notice_keeps_an_image_part_an_image():
{"type": "text", "text": "\n\nStop."},
]
assert _with_appended_text("Over the cap.", "\n\nStop.") == "Over the cap.\n\nStop."
+
+
+def test_no_post_tool_nudge_when_only_the_user_can_unblock(monkeypatch):
+ """The tool said to ask the user and the model asked; that reply is the answer."""
+ streams = [
+ [_tool_call_sse("web_search", {"query": "music"}, "call_first"), _done()],
+ [_sse({"content": "Load the music model and I will make the song."}), _done()],
+ [_sse({"content": "unreachable"}), _done()],
+ ]
+ backend, payloads = _backend_and_payloads(monkeypatch, streams)
+ _record_tool_calls(monkeypatch, "Error: [needs_user_load kind=audio page=Audio] Not loaded.")
+ messages = [{"role": "user", "content": "Make a song."}]
+ events = _run_tool_loop(
+ backend, messages, [_WEB_SEARCH_TOOL], max_tool_iterations = 3, nudge_tool_calls = True
+ )
+ content = "".join(e.get("text", "") for e in events if e.get("type") == "content")
+ assert len(payloads) == 2 and "I will make the song" in content
diff --git a/studio/backend/tests/test_load_policy.py b/studio/backend/tests/test_load_policy.py
new file mode 100644
index 00000000000..6e3f1cede3c
--- /dev/null
+++ b/studio/backend/tests/test_load_policy.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+from pathlib import Path
+
+import pytest
+from fastapi.security import HTTPAuthorizationCredentials
+
+from auth import authentication, storage
+from core.inference import load_policy as lp
+from utils.account_context import AccountContext, run_as
+
+from .mcp_harness import isolated_auth, owner_auth # noqa: F401 (fixtures)
+
+CHAT_KEY = storage.STUDIO_CHAT_TOOLS_KEY_NAME
+
+
+# A user's own key cannot opt into, or out of, the chat's policy by its name.
+ "name, internal, policy",
+ [
+ (CHAT_KEY, True, "beside_only"),
+ (storage.STUDIO_CHAT_TOOLS_API_KEY_NAME, True, "beside_only"),
+ (CHAT_KEY, False, "any"),
+ ("Data recipe", True, "any"),
+ ],
+)
[email protected]("owner_auth")
+def test_the_auth_layer_takes_the_policy_from_the_key(name, internal, policy):
+ key, _ = storage.create_api_key(username = "unsloth", name = name, internal = internal)
+ bearer = HTTPAuthorizationCredentials(scheme = "Bearer", credentials = key)
+
+ async def admit():
+ await authentication._get_current_credential(bearer, allow_password_change = False)
+ return lp.current_load_policy().value
+
+ assert asyncio.run(admit()) == policy
+
+
+# Only the owner's own UI chat loads beside without the switch; an unknown value reads as never.
+ "role, value, ui_chat, beside, read",
+ [
+ ("owner", "beside_only", True, True, "beside_only"),
+ ("owner", "beside_only", False, False, "beside_only"),
+ ("user", "beside_only", True, False, "beside_only"),
+ ("owner", "bogus", True, False, "never"),
+ ],
+)
+def test_owner_chat_loads_beside(role, value, ui_chat, beside, read):
+ account = AccountContext("a", "a", role, load_policy = value, ui_chat = ui_chat)
+ assert run_as(account, lp.owner_chat_loads_beside) is beside
+ assert run_as(account, lp.current_load_policy).value == read
+
+
+def test_routes_and_media_switch_do_not_read_the_mcp_caller():
+ for name in ("routes/inference.py", "routes/video.py", "core/inference/media_auto_switch.py"):
+ assert "studio_mcp" not in (Path(__file__).parents[1] / name).read_text(
+ encoding = "utf-8"
+ ), name
+
+
+# A chat an sk-unsloth key started mints the API-named key, so it never gets the owner's pass.
[email protected]("owner_auth")
+def test_a_chat_started_by_an_api_key_needs_the_switch():
+ from core.inference import studio_tools_mcp
+ from utils.account_context import current_account
+
+ async def chat_tools_pass(outer_key):
+ await authentication._get_current_credential(
+ HTTPAuthorizationCredentials(scheme = "Bearer", credentials = outer_key),
+ allow_password_change = False,
+ )
+ inner_key, _ = studio_tools_mcp._mint(current_account(), 30)
+ await authentication._get_current_credential(
+ HTTPAuthorizationCredentials(scheme = "Bearer", credentials = inner_key),
+ allow_password_change = False,
+ )
+ return lp.current_load_policy().value, lp.owner_chat_loads_beside()
+
+ api_key, _ = storage.create_api_key(username = "unsloth", name = "my client")
+ assert asyncio.run(chat_tools_pass(api_key)) == ("beside_only", False)
diff --git a/studio/backend/tests/test_mcp_access_route.py b/studio/backend/tests/test_mcp_access_route.py
index 973ce80ab94..c8560d338cd 100644
--- a/studio/backend/tests/test_mcp_access_route.py
+++ b/studio/backend/tests/test_mcp_access_route.py
@@ -8,7 +8,9 @@ from fastapi.testclient import TestClient
import storage.studio_db as studio_db
from auth import policy, storage
from auth.authentication import create_access_token
-from mcp_server import tool_catalog
+from mcp_server import tool_catalog, withheld
+
+CHAT_WITHHELD = set(withheld())
from routes import settings
from utils.keyless_api_access import set_keyless_api_access
from utils.mcp_access import (
@@ -65,8 +67,12 @@ def test_the_owner_session_reads_and_turns_it_on(client):
"enabled": False,
"forced_by_env": False,
"url": "http://127.0.0.1:8888/mcp/",
- "tools": [{**entry, "enabled": True} for entry in tool_catalog()],
+ "tools": [
+ {**entry, "enabled": True, "chat": entry["name"] not in CHAT_WITHHELD}
+ for entry in tool_catalog()
+ ],
}
+ assert {t["name"] for t in got.json()["tools"] if not t["chat"]} == CHAT_WITHHELD
put = client.put(URL, json = {"enabled": True}, headers = _owner_session())
assert put.status_code == 200, put.text
diff --git a/studio/backend/tests/test_mcp_audio_takes.py b/studio/backend/tests/test_mcp_audio_takes.py
index 0cfd1111973..b9fa3de0571 100644
--- a/studio/backend/tests/test_mcp_audio_takes.py
+++ b/studio/backend/tests/test_mcp_audio_takes.py
@@ -7,6 +7,7 @@ import pytest
from fastapi.responses import JSONResponse
from models.inference import AudioRunRequest
+from studio_mcp import audio_runs
from studio_mcp.tools import audio
from .mcp_harness import bodies, fake_studio, run_tool, sequence
@@ -60,7 +61,7 @@ def test_a_cancel_during_take_two_keeps_take_one_and_sends_no_third(monkeypatch)
def run(request, body):
if json.loads(body)["take"] == 1:
return _take("var-1", seed = 41)
- assert audio.stop_run("owner", "run-abc12") is False
+ assert audio_runs.stop_run("owner", "run-abc12") is False
return JSONResponse({"detail": "Audio generation cancelled"}, status_code = 499)
result, studio = _music(monkeypatch, run)
@@ -81,7 +82,7 @@ def test_a_cancel_during_take_two_keeps_take_one_and_sends_no_third(monkeypatch)
def test_a_cancel_as_a_take_ends_stops_before_the_next(monkeypatch):
def run(request, body):
- audio.stop_run("owner", "run-abc12")
+ audio_runs.stop_run("owner", "run-abc12")
return _take("var-1")
result, studio = _music(monkeypatch, run)
@@ -198,3 +199,20 @@ def test_an_unsaved_oversized_later_take_keeps_the_saved_takes(monkeypatch):
assert [c["id"] for c in out["clips"]] == ["var-1"] and out["group_id"]
assert "too large to return inline" in out["warnings"][-1]
assert len(bodies(studio, "/v1/audio/run")) == 2
+
+
[email protected]("named", [False, True])
+def test_takes_follow_the_music_model_kept_beside_the_chat_model(monkeypatch, named):
+ takes = iter(range(1, 10))
+ chat = {"active_model": "unsloth/Qwen-GGUF", "serving": ["unsloth/Qwen-GGUF", "ace-step"]}
+ music = {**_status("sequential"), "active_model": "ace-step"}
+
+ def status(request, body): # the bare status describes the chat model
+ return music if request.query_params.get("model") == "ace-step" else chat
+
+ run = {RUN: lambda request, body: _take(f"var-{next(takes)}"), STATUS: status, **GALLERY}
+ args = {**SONG, "model": "ace-step"} if named else SONG
+ result, studio = _music(monkeypatch, None, args = args, studio = fake_studio(run))
+ assert result["isError"] is False, result
+ # One request per take, as the kept model makes them, not one batch it would refuse.
+ assert [b.get("take") for b in bodies(studio, "/v1/audio/run")] == [1, 2, 3]
diff --git a/studio/backend/tests/test_mcp_errors.py b/studio/backend/tests/test_mcp_errors.py
index 388e82094c4..46e66e75221 100644
--- a/studio/backend/tests/test_mcp_errors.py
+++ b/studio/backend/tests/test_mcp_errors.py
@@ -1,16 +1,19 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+import contextvars
import json
import httpx
import pytest
from fastmcp.exceptions import ToolError
+from studio_mcp.caller import bind_caller
from studio_mcp.errors import raise_for_payload, raise_for_route, raise_for_status_field, tool_error
from studio_mcp.forward import ndjson_last
+from studio_mcp.profile import CHAT
-from .mcp_harness import DEFERRED, openai_error
+from .mcp_harness import DEFERRED, make_caller, openai_error
SENTINEL = "/srv/mcp-sentinel/models/secret.gguf"
WIN_SENTINEL = "C:\\mcp-sentinel\\models\\secret.gguf"
@@ -257,23 +260,26 @@ def _assert_always(message, tag = ALWAYS_TAG):
assert TOOL_HINT not in message
+ALWAYS_HEADERS = {"X-Unsloth-Problem": "multi_model_always kind=chat"} # the route's code
+
+
@pytest.mark.parametrize(
"resp",
[
- _padded({"status_code": 409, "detail": OWNER_ALWAYS}),
+ _padded({"status_code": 409, "detail": OWNER_ALWAYS, "headers": ALWAYS_HEADERS}),
_response(
409,
{"detail": OWNER_ALWAYS},
- headers = {"X-Unsloth-Refusal": "multi-model-always", "Retry-After": "5"},
+ headers = {**ALWAYS_HEADERS, "Retry-After": "5"},
),
- _response(409, {"detail": MANAGED_ALWAYS}),
- _v1(409, OWNER_ALWAYS, type = "conflict_error", param = "model", code = "multi_model_always"),
+ _response(409, {"detail": MANAGED_ALWAYS}, headers = ALWAYS_HEADERS),
+ _v1(409, OWNER_ALWAYS, code = "multi_model_always", headers = ALWAYS_HEADERS),
# A route that copies the headers into the padded body; the copy is not the marker text.
_padded(
{
"status_code": 409,
"detail": "Loading this model would unload the chat model x.",
- "headers": {"X-UNSLOTH-REFUSAL": "multi-model-always"},
+ "headers": {"X-UNSLOTH-PROBLEM": "multi_model_always kind=chat"},
}
),
_response(
@@ -287,7 +293,7 @@ def test_a_multi_model_always_refusal_is_tagged_and_names_unload_model(resp):
def test_a_multi_model_always_refusal_of_an_unknown_kind_keeps_a_bare_tag():
- resp = _response(409, {"detail": "Keep multiple models loaded is set to Always."})
+ resp = _response(409, {"detail": "No."}, headers = {"X-Unsloth-Problem": "multi_model_always"})
message = _message(resp, hints = {409: TOOL_HINT})
assert message.startswith("[multi_model_always] ")
assert message.endswith(
@@ -295,6 +301,20 @@ def test_a_multi_model_always_refusal_of_an_unknown_kind_keeps_a_bare_tag():
)
+ "resp",
+ [
+ _response(409, {"detail": OWNER_ALWAYS}),
+ _response(409, {"detail": MANAGED_ALWAYS}),
+ _response(400, {"detail": "No model loaded."}),
+ _v1(503, "No GGUF model loaded. Load a GGUF model first."),
+ ],
+)
+def test_the_wording_alone_is_not_read_as_a_problem(resp):
+ message = _message(resp)
+ assert not message.startswith("[") and "load_model" not in message
+
+
def test_always_wording_on_another_status_is_not_a_refusal():
message = _message(_response(500, {"detail": "Keep multiple models loaded is set to Always."}))
assert not message.startswith("[")
@@ -374,60 +394,58 @@ def _at(status, body, path):
)
+def _tag(kind):
+ return {"X-Unsloth-Problem": f"not_loaded kind={kind}"}
+
+
@pytest.mark.parametrize(
"resp,kind",
[
- (_at(400, {"detail": "No model loaded."}, "/v1/audio/run"), "audio"),
- (_at(400, {"detail": "No model loaded."}, "/v1/audio/transcriptions"), "stt"),
- (_at(409, {"detail": "No model loaded"}, "/api/inference/audio/stt/load"), "stt"),
- (_at(400, {"detail": "No model loaded."}, "/v1/images/generations"), "image"),
- (_at(400, {"detail": "No model loaded."}, "/v1/chat/completions"), "chat"),
- (_at(400, {"detail": "No model loaded."}, "/api/inference/unload"), "chat"),
- (_response(409, {"detail": "No diffusion model is loaded."}), "image"),
- (_response(503, {"detail": "No video model loaded. Load a video model first."}), "video"),
- (_v1(400, "No model loaded. Call POST /inference/load first."), "chat"),
- (
- _at(
- 503, {"detail": "No GGUF model loaded. Load a GGUF model first."}, "/v1/embeddings"
- ),
- "chat",
- ),
- (
- _at(
- 503,
- {"detail": "No image model loaded. Load an image model first."},
- "/v1/images/generations",
- ),
- "image",
- ),
- ],
- ids = [
- "audio-path",
- "stt-v1-path",
- "stt-api-path",
- "image-path",
- "chat-path",
- "unload-path",
- "diffusion-wording",
- "video-wording",
- "no-request",
- "gguf-wording",
- "image-wording",
+ (_response(400, {"detail": "No model loaded."}, headers = _tag("audio")), "audio"),
+ (_response(409, {"detail": "No model"}, headers = _tag("stt")), "stt"),
+ (_v1(400, "No model loaded.", headers = _tag("llm")), "llm"),
+ (_padded({"status_code": 400, "detail": "No one.", "headers": _tag("image")}), "image"),
],
)
def test_not_loaded_names_the_kind(resp, kind):
assert _message(resp).startswith(f"[not_loaded kind={kind}] No ")
-def test_a_deferred_not_loaded_uses_the_route_path():
- padded = httpx.Response(
- 200,
- content = json.dumps(
- {"_deferred_error": {"status_code": 400, "detail": "No model loaded."}}
- ).encode(),
- request = httpx.Request("POST", "http://x/api/inference/audio/load"),
- )
- assert _message(padded).startswith("[not_loaded kind=audio] ")
+MUSIC = "audio-cpp/audio.cpp-gguf/Stable-Audio-3-Small-Music-GGUF"
+
+
+def _message_as(chat, resp, **kwargs):
+ context = contextvars.copy_context()
+ if chat:
+ context.run(bind_caller, make_caller(profile = CHAT, direct_local = False))
+ return context.run(_message, resp, **kwargs)
+
+
+def _problem(code, status):
+ headers = {"X-Unsloth-Problem": f"{code} kind=audio model={MUSIC} page=Audio"}
+ return _v1(status, "Not here.", code = code, headers = headers)
+
+
+ "resp, chat, says",
+ [
+ (_problem("not_loaded", 400), False, "with load_model(kind='tts') first."),
+ (_problem("not_loaded", 400), True, "on the Audio page in Unsloth Studio, then try again."),
+ # Only the user can: no tool, and no hint repeating the route's message.
+ (_problem("needs_user_load", 403), False, "kind=audio page=Audio] Not here. (HTTP 403)"),
+ (_problem("needs_user_load", 403), True, "kind=audio page=Audio] Not here. (HTTP 403)"),
+ (_problem("needs_download", 404), False, f"download_model(model='{MUSIC}', kind='audio')"),
+ (_problem("needs_download", 404), True, f"download_model(model='{MUSIC}', kind='audio')"),
+ (_response(409, {"detail": OWNER_ALWAYS}, headers = ALWAYS_HEADERS), True, ""),
+ (_response(409, {"detail": ACTIVE}), True, ""),
+ ],
+)
+def test_a_problem_hint_fits_the_callers_tools(resp, chat, says):
+ message = _message_as(chat, resp, hints = {400: "Load one."})
+ assert says in message
+ if chat or "page=Audio]" in says:
+ # A chat's tools call loads, unloads and cancels nothing itself.
+ assert "load_model(kind" not in message and "cancel(" not in message
NOISE = [f"load_tensors: layer {i} assigned to device CUDA0" for i in range(300)]
@@ -475,3 +493,16 @@ def test_a_tag_that_is_not_a_plain_code_is_dropped():
assert str(tool_error("boom", "Try again.", tag = "out_of_memory")).startswith(
"[out_of_memory] boom Try again."
)
+
+
+def test_a_hint_never_names_a_tool_the_owner_turned_off(monkeypatch):
+ from studio_mcp import problems
+ from utils import mcp_access
+
+ monkeypatch.setattr(mcp_access, "disabled_tools", lambda: frozenset({"download_model"}))
+ tools = problems.caller_tools()
+ assert "download_model" not in tools and "load_model" in tools
+ assert problems.download_hint("image", "org/m", tools).startswith("Ask the user to load")
+ # Unsloth MCP off: every tool counts as off, so no hint names one.
+ monkeypatch.setattr(mcp_access, "disabled_tools", lambda: None)
+ assert problems.caller_tools() == frozenset()
diff --git a/studio/backend/tests/test_mcp_jobs_module.py b/studio/backend/tests/test_mcp_jobs_module.py
new file mode 100644
index 00000000000..e86787fc534
--- /dev/null
+++ b/studio/backend/tests/test_mcp_jobs_module.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import types
+
+import pytest
+from fastmcp.exceptions import ToolError
+
+from studio_mcp import export_jobs, jobs
+from studio_mcp.media import media_result
+from studio_mcp.outputs import JobStatus
+from studio_mcp.tools import audio
+from studio_mcp.tools import cancel as cancel_tool
+from studio_mcp.tools import jobs as jobs_tool
+
+from .mcp_harness import fake_studio, register_export_job, run_tool, session
+
+CANCEL = "/api/inference/audio/cancel"
+
+
+def _reset():
+ audio._RUNS.clear()
+ audio._CANCELLED.clear()
+ export_jobs._reset()
+
+
[email protected](autouse = True)
+def fresh_jobs():
+ _reset()
+ yield
+ _reset()
+
+
+def test_a_cancelled_audio_id_is_refused_for_a_new_run(monkeypatch):
+ studio = fake_studio({("POST", CANCEL): {"cancelled": 0}})
+ with session(monkeypatch, studio) as call:
+ call("cancel", {"kind": "audio", "id": "run-old-1"})
+ args = {"workflow": "speak", "text": "hi", "cancel_id": "run-old-1"}
+ again = call("generate_audio", args)
+ assert again["isError"] is True and "pass a new cancel_id" in again["content"][0]["text"]
+ assert [c[1] for c in studio.state.calls] == [CANCEL]
+
+
[email protected]("status, poll", [("completed", None), ("running", 15)])
+def test_an_export_job_reads_with_a_poll_hint_only_while_running(monkeypatch, status, poll):
+ register_export_job(job_id = "exp-1", status = status)
+ result, _studio = run_tool(monkeypatch, {}, "get_job", {"kind": "export", "id": "exp-1"})
+ job = result["structuredContent"]
+ assert (job["status"], job["poll_after_s"]) == (status, poll)
+
+
+def test_a_registered_kind_is_reached_by_get_job_and_cancel(monkeypatch):
+ seen = []
+
+ async def read(caller, job_id, **_options):
+ seen.append(("read", caller.account_id, job_id))
+ return media_result([], JobStatus(kind = "video", id = job_id, status = "running"))
+
+ async def stop(caller, job_id, save):
+ seen.append(("cancel", caller.account_id, job_id, save))
+ return jobs.Stop(True, "stopped", job_id)
+
+ monkeypatch.setattr(jobs, "KINDS", dict(jobs.KINDS))
+ jobs.register(jobs.Kind("fake", read = read, cancel = stop, poll_after_s = 7, needs_id = "id"))
+ owner = types.SimpleNamespace(account_id = "owner")
+ for module in (jobs_tool, cancel_tool):
+ monkeypatch.setattr(module, "current_caller", lambda: owner)
+
+ assert asyncio.run(jobs_tool.get_job("fake", "f-1")).structured_content["poll_after_s"] == 7
+ stopped = asyncio.run(cancel_tool.cancel("fake", "f-1", save = False))
+ assert (stopped.kind, stopped.id, stopped.cancelled) == ("fake", "f-1", True)
+ assert seen == [("read", "owner", "f-1"), ("cancel", "owner", "f-1", False)]
+ with pytest.raises(ToolError, match = "needs id: id"):
+ asyncio.run(cancel_tool.cancel("fake"))
+ for tool in (jobs_tool.get_job("nope", "x"), cancel_tool.cancel("nope", "x")):
+ with pytest.raises(ToolError, match = "Unknown job kind"):
+ asyncio.run(tool)
diff --git a/studio/backend/tests/test_mcp_profile_surface.py b/studio/backend/tests/test_mcp_profile_surface.py
new file mode 100644
index 00000000000..bc4f5f89422
--- /dev/null
+++ b/studio/backend/tests/test_mcp_profile_surface.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Each caller profile reads only about the tools it was given, at a bounded cost per message."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+
+import pytest
+
+from mcp_server import create_studio_mcp, surface, withheld
+from studio_mcp import surface as text_surface
+from studio_mcp.profile import AGENT, CHAT, CallerProfile, OUTLIVES_CALL
+
+# What the chat model reads on every message, in characters. 52,513 before profiles, 47,499 with
+# them; lower it when the surface shrinks, never raise it to fit.
+CHAT_BUDGET_CHARS = 48_000
+
+
+def _texts(profile):
+ tools = asyncio.run(create_studio_mcp(profile).list_tools())
+ return {t.name: t.to_mcp_tool() for t in tools}
+
+
+def test_chat_withholds_each_tool_by_its_facts_and_never_names_one():
+ absent = set(withheld(CHAT))
+ assert absent == {"load_model", "unload_model", "plan_load", "chat", "run_recipe"} | {
+ "start_training",
+ "export_model",
+ "cancel",
+ }
+ tools = _texts(CHAT)
+ assert not absent & set(tools)
+ # Called like a tool or named in prose; `cancel_id` and "cancel" as a verb are not the tool.
+ names = "|".join(sorted(re.escape(n) for n in absent - {"chat", "cancel"}))
+ named = re.compile(rf"\b({names})(\(|\b(?![_ ]?(id|ids)\b))|\b(chat|cancel)\(")
+ for name, t in tools.items():
+ text = json.dumps([t.description, t.inputSchema, t.outputSchema])
+ assert not named.search(text) and "<<" not in text, name
+ if "name one in ``model``" in (t.description or ""):
+ assert "model" in t.inputSchema.get("properties", {}), name
+ size = sum(
+ len(json.dumps({"n": n, "d": t.description, "p": t.inputSchema})) for n, t in tools.items()
+ )
+ assert size <= CHAT_BUDGET_CHARS, size
+
+
+def test_agent_text_still_points_at_load_model():
+ tools = _texts(AGENT)
+ assert 'load_model(kind="image")' in tools["generate_image"].description
+ for name, t in tools.items():
+ assert "<<" not in json.dumps([t.description, t.inputSchema, t.outputSchema]), name
+
+
+def test_a_profile_withholds_by_the_facts_tools_declare():
+ narrow = CallerProfile("narrow", refused = frozenset({OUTLIVES_CALL}))
+ assert surface(narrow) == surface(AGENT) - {"start_training", "export_model"}
+
+
+ "text, tools, expected",
+ [
+ ("Load <<load_model: with it | on the Image page>>.", {"load_model"}, "Load with it."),
+ ("Load <<load_model: with it | on the Image page>>.", set(), "Load on the Image page."),
+ ("Done.<<cancel: Stop it with cancel(kind='video').>>", set(), "Done."),
+ (
+ "Save a .csv, .json or .parquet file<<datasets: here>>.",
+ set(),
+ "Save a .csv, .json or .parquet file.",
+ ),
+ (
+ "Not known yet<<load_model: , so pass the kind>>.",
+ {"load_model"},
+ "Not known yet, so pass the kind.",
+ ),
+ ("Not known yet<<load_model: , so pass the kind>>.", set(), "Not known yet."),
+ ],
+)
+def test_render(text, tools, expected):
+ assert text_surface.render(text, tools) == expected
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index 48b2c5c4be1..4011990ea42 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -2855,6 +2855,54 @@ def test_controller_without_the_search_tool_never_loads_mcp_tools(tmp_path, monk
assert controller.active_tools() == []
+STUDIO_TOOLS_URL = "http://127.0.0.1/mcp/studio-tools"
+
+
[email protected]("credential", ["via_api_key", "no_credential"])
+def test_only_the_ui_can_add_or_repoint_the_studio_tools_row(tmp_path, monkeypatch, credential):
+ import asyncio
+ import routes.mcp_servers as routes
+ from models.mcp_servers import McpServerCreate, McpServerImportRequest, McpServerUpdate
+
+ _reset_db(tmp_path, monkeypatch)
+ mcp_servers_db.create_server(id = "web", display_name = "Web", url = "https://a/mcp")
+ add = McpServerCreate(display_name = "Unsloth Studio", url = STUDIO_TOOLS_URL)
+ studio = asyncio.run(routes.create_mcp_server(add, current_subject = "u")).id
+ key = {"current_subject": "u", credential: True}
+ for refused in (
+ routes.create_mcp_server(add, **key),
+ routes.update_mcp_server("web", McpServerUpdate(url = STUDIO_TOOLS_URL), **key),
+ routes.update_mcp_server(studio, McpServerUpdate(url = "https://b/mcp"), **key),
+ ):
+ with pytest.raises(HTTPException) as exc:
+ asyncio.run(refused)
+ assert exc.value.status_code == 403
+ config = {"mcpServers": {"studio": {"url": "http://localhost:8888/mcp/studio-tools"}}}
+ result = asyncio.run(routes.import_mcp_servers(McpServerImportRequest(config = config), **key))
+ assert result.created == [] and len(result.errors) == 1
+ off = asyncio.run(routes.update_mcp_server(studio, McpServerUpdate(is_enabled = False), **key))
+ assert off.is_enabled is False and off.url == STUDIO_TOOLS_URL
+
+
+def test_the_studio_tools_row_is_reprobed_every_send_and_never_falls_back(tmp_path, monkeypatch):
+ import asyncio
+ from unittest.mock import AsyncMock
+
+ from core.inference import mcp_client, tools as tools_mod
+
+ _reset_db(tmp_path, monkeypatch)
+ monkeypatch.setattr(mcp_client, "_tool_cache", {})
+ monkeypatch.setattr(mcp_client, "_probe_cooloff_until", {})
+ for id, url in (("web", "https://x"), ("studio", STUDIO_TOOLS_URL)):
+ mcp_servers_db.create_server(id = id, display_name = id, url = url, is_enabled = True)
+ answers = [_one_tool(), _one_tool("a"), _one_tool("b"), RuntimeError("listing failed")]
+ monkeypatch.setattr(tools_mod, "list_tools_async", fake := AsyncMock(side_effect = answers))
+ for studio_tools in (["mcp__studio__a"], ["mcp__studio__b"], []):
+ listed = asyncio.run(tools_mod.get_enabled_mcp_tools())
+ assert [t["function"]["name"] for t in listed] == ["mcp__web__echo", *studio_tools]
+ assert [c.kwargs["url"] for c in fake.call_args_list] == ["https://x", *[STUDIO_TOOLS_URL] * 3]
+
+
@pytest.mark.parametrize("searched", [False, True])
def test_deferred_mcp_calls_keep_catalog_coercion_on_every_call(monkeypatch, searched):
from core.inference import tool_loop_controller as controller_mod
diff --git a/studio/backend/tests/test_mcp_tool_contract.py b/studio/backend/tests/test_mcp_tool_contract.py
index c53d6683ffb..cc325e4fa46 100644
--- a/studio/backend/tests/test_mcp_tool_contract.py
+++ b/studio/backend/tests/test_mcp_tool_contract.py
@@ -8,7 +8,9 @@ from typing import Optional
import pytest
from fastapi.responses import JSONResponse
-from studio_mcp.errors import ACTIVE_GENERATIONS_HINT
+from mcp_server import surface
+from studio_mcp import problems
+from studio_mcp.profile import AGENT
from studio_mcp.inputs import PATH_REMOTE
from studio_mcp.outputs import RouteText, ToolOutput, Usage
@@ -152,14 +154,24 @@ ACTIVE_GENERATIONS = {
"thread_ids": ["thread-a", "thread-b"],
}
STT_LOAD = ("POST", "/api/inference/audio/stt/load")
+ACTIVE_GENERATIONS_HINT = problems.wait_hint(surface(AGENT))
+
+
+def _not_loaded(kind):
+ return {"X-Unsloth-Problem": f"not_loaded kind={kind}"}
+
+
+def _no_model(message, status, kind):
+ return openai_error(message, status, headers = _not_loaded(kind))
+
# (tool, args, the studio's routes, then the whole message or (check, text) pairs).
ROUTE_ERRORS = [
(
"chat",
{"prompt": "hi"},
- {CHAT: openai_error("No model loaded. Call POST /inference/load first.", 400)},
- ("starts", "[not_loaded kind=chat] No model loaded. (HTTP 400) "),
+ {CHAT: _no_model("No model loaded. Call POST /inference/load first.", 400, "llm")},
+ ("starts", "[not_loaded kind=llm] No model loaded. (HTTP 400) "),
("ends", "Load a chat model with load_model first; list_models shows the downloaded ones."),
),
(
@@ -206,7 +218,7 @@ ROUTE_ERRORS = [
(
"generate_audio",
{"workflow": "speak", "text": "Hi"},
- {("POST", "/v1/audio/run"): openai_error("No model loaded.", 400)},
+ {("POST", "/v1/audio/run"): _no_model("No model loaded.", 400, "audio")},
("starts", "[not_loaded kind=audio] "),
(
"ends",
@@ -246,7 +258,7 @@ ROUTE_ERRORS = [
(
"generate_video",
{"prompt": "waves"},
- {("POST", "/v1/videos"): openai_error("No video model is loaded.", 503)},
+ {("POST", "/v1/videos"): _no_model("No video model is loaded.", 503, "video")},
("starts", "[not_loaded kind=video] "),
(
"ends",
@@ -257,7 +269,7 @@ ROUTE_ERRORS = [
(
"generate_image",
{"prompt": "x"},
- {IMAGES: _detail("No diffusion model is loaded.", 409)},
+ {IMAGES: _detail("No diffusion model is loaded.", 409, **_not_loaded("image"))},
("starts", "[not_loaded kind=image] "),
(
"ends",
diff --git a/studio/backend/tests/test_mcp_tools_audio.py b/studio/backend/tests/test_mcp_tools_audio.py
index a23e612dbe0..fcbca136384 100644
--- a/studio/backend/tests/test_mcp_tools_audio.py
+++ b/studio/backend/tests/test_mcp_tools_audio.py
@@ -624,3 +624,16 @@ def test_a_slow_song_sends_a_heartbeat_and_still_returns_its_clip(monkeypatch):
assert result["structuredContent"]["clips"][0]["id"] == "clip-1"
assert len(progress) >= 2
assert all(p["message"].startswith("Generating audio") for p in progress)
+
+
+def test_options_are_checked_against_the_speech_model_kept_beside_the_chat_model(monkeypatch):
+ chat = {"active_model": "unsloth/Qwen-GGUF", "serving": ["unsloth/Qwen-GGUF", "org/Speech"]}
+ speech = {**CUSTOM_VOICE, "active_model": "org/Speech", "is_audio": True}
+
+ def status(request, body):
+ return speech if request.query_params.get("model") == "org/Speech" else chat
+
+ args = {"workflow": "speak", "text": "Hi", "options": {"voice": "Bob"}}
+ result, studio = _generate(monkeypatch, args, routes = {("GET", "/api/inference/status"): status})
+ assert result["isError"] is True and "'Bob' is not one of" in result["content"][0]["text"]
+ assert bodies(studio, "/v1/audio/run") == []
diff --git a/studio/backend/tests/test_mcp_tools_cancel.py b/studio/backend/tests/test_mcp_tools_cancel.py
index 4b5bb75f8b6..c3a10a046a8 100644
--- a/studio/backend/tests/test_mcp_tools_cancel.py
+++ b/studio/backend/tests/test_mcp_tools_cancel.py
@@ -165,6 +165,7 @@ NOT_RUNNING = {"success": True, "message": "No active export to cancel"}
def _cancel_directly(monkeypatch, job_run, answers):
"""Run cancel on the loop the job's task lives on, which a served tool call cannot share."""
+ from studio_mcp import job_kinds
from studio_mcp.tools import cancel as cancel_module
answer = sequence(*answers)
@@ -179,11 +180,11 @@ def _cancel_directly(monkeypatch, job_run, answers):
calls.append((method, path, json_body))
return answer(None, None)
- monkeypatch.setattr(cancel_module, "route_json", route_json)
+ monkeypatch.setattr(job_kinds, "route_json", route_json)
monkeypatch.setattr(
cancel_module, "current_caller", lambda: types.SimpleNamespace(account_id = "owner")
)
- monkeypatch.setattr(cancel_module, "SETTLE_S", 0.2)
+ monkeypatch.setattr(job_kinds, "SETTLE_S", 0.2)
async def run():
job = export_jobs.start("owner", "gguf", job_run)
diff --git a/studio/backend/tests/test_mcp_tools_jobs.py b/studio/backend/tests/test_mcp_tools_jobs.py
index 19568378c54..0fabdf70cdf 100644
--- a/studio/backend/tests/test_mcp_tools_jobs.py
+++ b/studio/backend/tests/test_mcp_tools_jobs.py
@@ -252,9 +252,9 @@ def test_a_status_read_that_stalls_never_holds_a_wait_past_wait_s(monkeypatch, f
def test_a_first_read_that_stalls_ends_with_a_retry_hint(monkeypatch):
- from studio_mcp.tools import jobs
+ from studio_mcp import jobs as job_reads
- monkeypatch.setattr(jobs, "FIRST_READ_S", 0.2)
+ monkeypatch.setattr(job_reads, "FIRST_READ_S", 0.2)
studio = fake_studio({VIDEO: slow(_video("in_progress", 10), 10)})
started = time.monotonic()
result, _studio = run_tool(monkeypatch, studio, "get_job", {"kind": "video", "id": "vid-1"})
diff --git a/studio/backend/tests/test_mcp_tools_loading.py b/studio/backend/tests/test_mcp_tools_loading.py
index e7a16bf95fe..a523a3995d0 100644
--- a/studio/backend/tests/test_mcp_tools_loading.py
+++ b/studio/backend/tests/test_mcp_tools_loading.py
@@ -1402,7 +1402,13 @@ def test_a_padded_keep_loaded_refusal_names_unload_model(monkeypatch):
"Loading this model would unload the chat model unsloth/Qwen3-0.6B, and Keep multiple"
" models loaded is set to Always. Unload that model first, or choose When they fit."
)
- padded = " " * 40 + json.dumps({"_deferred_error": {"status_code": 409, "detail": refusal}})
+ # The headers the load route copies into a padded answer.
+ headers = {
+ "x-unsloth-refusal": "multi-model-always",
+ "x-unsloth-problem": "multi_model_always kind=chat",
+ }
+ deferred = {"status_code": 409, "detail": refusal, "headers": headers}
+ padded = " " * 40 + json.dumps({"_deferred_error": deferred})
routes = {**PAYLOADS, LOAD: Response(padded.encode(), media_type = "application/json")}
result, _studio = run_tool(monkeypatch, routes, "load_model", {"model": LLM})
message = result["content"][0]["text"]
diff --git a/studio/backend/tests/test_mcp_video_queue.py b/studio/backend/tests/test_mcp_video_queue.py
index eeb11e7e7a3..0f6e5dd1894 100644
--- a/studio/backend/tests/test_mcp_video_queue.py
+++ b/studio/backend/tests/test_mcp_video_queue.py
@@ -13,6 +13,7 @@ from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from studio_mcp import video_queue
+from studio_mcp.profile import CHAT
from .mcp_harness import call_tool, fake_studio, make_caller, openai_error, run_tool, served
@@ -29,6 +30,9 @@ GPU_BUSY = JSONResponse(
status_code = 409,
headers = {"Retry-After": "0"},
)
+NO_MODEL = openai_error(
+ "No video model is loaded.", 503, headers = {"X-Unsloth-Problem": "not_loaded kind=video"}
+)
ETA = 30.0
@@ -226,7 +230,7 @@ def test_a_settled_record_drops_its_request_and_caller(monkeypatch):
[
(MODEL_CHANGED, "[model_changed] The requested video model changed"),
(GPU_BUSY, "GPU busy: Another account is generating. Retry after 0 s."),
- (openai_error("No video model is loaded.", 503), "Load a video model with load_model"),
+ (NO_MODEL, "Load a video model with load_model"),
],
)
def test_other_refusals_raise_as_before_and_queue_nothing(monkeypatch, answer, text):
@@ -379,3 +383,15 @@ def test_a_stalled_eta_read_leaves_the_eta_unknown(monkeypatch):
monkeypatch.setattr(video_queue, "READ_S", 0.05)
item = video_queue._enqueue(make_caller(account_id = "a"), {"prompt": "x"}, None)
assert asyncio.run(video_queue._position_eta(item)) == (1, None)
+
+
+def test_a_call_scoped_caller_is_told_to_retry_instead_of_queued():
+ # The chat bridge's key is revoked when its call returns, so a clip queued for later would 401.
+ fake = OneVideoStudio()
+ agent = make_caller(studio_app = fake.app)
+ assert asyncio.run(video_queue.post_or_queue(agent, {"prompt": "A"}))["id"] == "video-1"
+ chat = make_caller(studio_app = fake.app, profile = CHAT)
+ with pytest.raises(ToolError, match = r"(?s)^\[gpu_busy\].*Try again once it finishes"):
+ asyncio.run(video_queue.post_or_queue(chat, {"prompt": "B"}))
+ assert not video_queue._waiting.get("owner") and not video_queue._pumps
+ assert fake.prompts() == ["A", "B"]
diff --git a/studio/backend/tests/test_media_auto_switch.py b/studio/backend/tests/test_media_auto_switch.py
index 125982e9a4c..252eadeba16 100644
--- a/studio/backend/tests/test_media_auto_switch.py
+++ b/studio/backend/tests/test_media_auto_switch.py
@@ -425,6 +425,85 @@ def test_a_video_refusal_carries_a_plain_detail(catalog, enabled, loads):
assert isinstance(excinfo.value.detail, str)
[email protected]("takes_the_gpu, evicts", [(True, True), (True, False), (False, True)])
+def test_a_chat_tools_key_switches_media_only_when_the_chat_model_stays(
+ flux, enabled, loads, monkeypatch, takes_the_gpu, evicts
+):
+ from dataclasses import replace
+
+ from utils.account_context import OWNER, run_as
+
+ key = replace(OWNER, via_api_key = True, load_policy = "beside_only")
+ monkeypatch.setattr(backends, "load_takes_the_gpu", lambda: takes_the_gpu)
+ monkeypatch.setattr(mas, "load_takes_the_gpu", lambda: takes_the_gpu)
+ monkeypatch.setattr(arb, "would_evict", lambda owner, **_kw: evicts)
+ problem, refused = "", takes_the_gpu and evicts
+ try:
+ run_as(key, _switch, "black-forest-labs/FLUX.1-dev")
+ except HTTPException as exc:
+ problem = exc.headers["X-Unsloth-Problem"]
+ assert problem.startswith("needs_user_load kind=image") == refused and len(loads) == 1 - refused
+
+
+ "key_policy, parent_counted, chats, switched",
+ [
+ ("beside_only", True, 1, True), # the one counted chat is the caller's own
+ ("beside_only", True, 2, False), # another chat is still busy
+ (
+ "beside_only",
+ False,
+ 1,
+ False,
+ ), # an external-provider parent is not counted: the 1 is someone else
+ ("any", True, 1, False),
+ ],
+)
+def test_a_chat_tools_switch_does_not_wait_on_the_chat_that_called_it(
+ flux, enabled, loads, monkeypatch, key_policy, parent_counted, chats, switched
+):
+ from dataclasses import replace
+
+ from core.inference import load_policy
+ from utils.account_context import OWNER, run_as
+
+ key = replace(OWNER, via_api_key = True, load_policy = key_policy, key_id = 41)
+ if parent_counted:
+ load_policy.note_counted_parent(41)
+ monkeypatch.setattr(backends, "load_takes_the_gpu", lambda: True)
+ monkeypatch.setattr(mas, "load_takes_the_gpu", lambda: True)
+ monkeypatch.setattr(mas, "_DRAIN_WAIT_S", 0.2)
+ monkeypatch.setattr(arb, "would_evict", lambda owner, **_kw: False)
+ monkeypatch.setattr(chat, "other_inference_request_count", lambda **kw: chats)
+ try:
+ run_as(key, _switch, "black-forest-labs/FLUX.1-dev")
+ problem = ""
+ except HTTPException as exc:
+ problem = (exc.headers or {}).get("X-Unsloth-Problem", str(exc.detail))
+ finally:
+ load_policy.forget_counted_parent(41)
+ assert (len(loads) == 1) == switched, problem
+
+
+def test_a_chat_model_that_lands_before_the_gates_still_refuses_a_chat_tools_switch(
+ flux, enabled, loads, monkeypatch, takes_the_gpu
+):
+ from dataclasses import replace
+
+ from utils.account_context import OWNER, run_as
+
+ key = replace(OWNER, via_api_key = True, load_policy = "beside_only")
+ # The precheck sees no chat model; one is resident by the time the media gates are held.
+ checks: list = []
+ monkeypatch.setattr(
+ arb, "would_evict", lambda owner, **_kw: checks.append(owner) or len(checks) > 1
+ )
+ with pytest.raises(HTTPException) as excinfo:
+ run_as(key, _switch, "black-forest-labs/FLUX.1-dev")
+ assert excinfo.value.headers["X-Unsloth-Problem"].startswith("needs_user_load kind=image")
+ assert loads == [] and len(checks) == 2
+
+
@pytest.mark.parametrize("resident", ["repo id", "path"])
def test_a_resident_model_is_not_reloaded(flux, enabled, backend, loads, resident):
backend.repo_id = "black-forest-labs/FLUX.1-dev" if resident == "repo id" else str(flux)
diff --git a/studio/backend/tests/test_mlx_diffusion_routing.py b/studio/backend/tests/test_mlx_diffusion_routing.py
index 50540f75303..8acdf2db2fb 100644
--- a/studio/backend/tests/test_mlx_diffusion_routing.py
+++ b/studio/backend/tests/test_mlx_diffusion_routing.py
@@ -1442,7 +1442,10 @@ def test_the_fallback_is_refused_when_it_does_not_fit_under_always(rig, route_ga
_img2img(rig.engine)
http = excinfo.value.http
assert http.status_code == 409
- assert http.headers == dict(arb.MULTI_MODEL_REFUSAL_HEADERS)
+ assert http.headers == {
+ **arb.MULTI_MODEL_REFUSAL_HEADERS,
+ "X-Unsloth-Problem": "multi_model_always kind=chat",
+ }
assert rig.log == []
assert rig.engine.status()["engine_routing"]["resident"] == ["mlx"]
diff --git a/studio/backend/tests/test_multi_model_always.py b/studio/backend/tests/test_multi_model_always.py
index 1b5c68153a9..ec817301d9f 100644
--- a/studio/backend/tests/test_multi_model_always.py
+++ b/studio/backend/tests/test_multi_model_always.py
@@ -580,6 +580,8 @@ def test_a_padded_refusal_keeps_its_header(route):
deferred = json.loads(b"".join(asyncio.run(run())))["_deferred_error"]
assert deferred["status_code"] == 409 and "is set to Always" in deferred["detail"]
+ # The problem code rides along, so an MCP agent still gets the tag after a padded answer.
+ assert deferred["headers"].pop("x-unsloth-problem") == "multi_model_always kind=chat"
assert deferred["headers"] == {"x-unsloth-refusal": REFUSAL}
diff --git a/studio/backend/tests/test_multi_model_serving.py b/studio/backend/tests/test_multi_model_serving.py
index 1aeee3c57e3..14ec1d6d4b3 100644
--- a/studio/backend/tests/test_multi_model_serving.py
+++ b/studio/backend/tests/test_multi_model_serving.py
@@ -7,6 +7,7 @@ import asyncio
import inspect
import threading
from types import SimpleNamespace
+from unittest.mock import AsyncMock
import pytest
from fastapi import FastAPI, HTTPException
@@ -121,6 +122,34 @@ def test_a_safetensors_slot_is_served_by_its_own_orchestrator(backends):
assert asyncio.run(run()) == (safetensors, False, safetensors.orchestrator)
+def _serving(info):
+ return SimpleNamespace(active_model_name = "org/Audio", models = {"org/Audio": info})
+
+
+_MUSIC, _SPEECH = {"audio_music": {"modes": []}}, {"is_audio": True, "audio_type": "csm"}
+
+
+ "workflow, primary, kept",
+ [
+ ("separate", None, [_SPEECH, {"is_audio": True, "audio_workflows": ["separate"]}]),
+ ("music", None, [_SPEECH, _MUSIC]),
+ ("music", _MUSIC, [_MUSIC]), # the primary runs it: stays there
+ ],
+)
+def test_omitted_audio_model_routes_to_the_kept_one(backends, monkeypatch, workflow, primary, kept):
+ if primary:
+ monkeypatch.setattr(orchestrator, "_inference_backend", _serving(primary))
+ model_slots.slots[:] = [model_slots.ExtraSlot(FakeLlama(), _serving(i), "owner") for i in kept]
+
+ async def run():
+ await inf._route_to_kept_audio_model(workflow)
+ return inf.get_inference_backend()
+
+ want = orchestrator._inference_backend if primary else model_slots.slots[-1].orchestrator
+ assert asyncio.run(run()) is want
+
+
def test_loaded_models_lists_every_backend(backends):
app = FastAPI()
app.include_router(inf.studio_router, prefix = "/api/inference")
@@ -495,6 +524,42 @@ def test_a_model_that_fits_nowhere_beside_the_others_replaces_the_active_one(bac
assert primary.model_identifier == "org/C-GGUF" and primary.is_loaded
+BESIDE_ONLY = AccountContext("owner", "o", "owner", via_api_key = True, load_policy = "beside_only")
+
+
[email protected]("alongside, short_fits", [(True, [1, 1]), (False, [])])
+def test_a_beside_only_load_unloads_nothing(backends, monkeypatch, alongside, short_fits):
+ a, b = backends
+ b.request = LoadRequest(model_path = "org/B-GGUF", gguf_variant = "Q8_0")
+ monkeypatch.setattr(multi_model_settings, "get_multi_model_mode", lambda: "fit")
+ _gated_load_fakes(monkeypatch, short_fits = short_fits)
+ request = LoadRequest(model_path = "org/C-GGUF", alongside = alongside)
+ with pytest.raises(HTTPException) as exc:
+ run_as(BESIDE_ONLY, asyncio.run, inf.load_model_gated(request, None, "s"))
+ assert exc.value.headers["X-Unsloth-Problem"].startswith("needs_user_load kind=llm")
+ assert a.is_loaded and a.model_identifier == "org/A-GGUF" and model_slots.slots == [b]
+
+
+def test_a_beside_only_load_into_an_empty_primary_frees_only_media(backends, monkeypatch):
+ backends[0].unload_model()
+ monkeypatch.setattr(multi_model_settings, "get_multi_model_mode", lambda: "fit")
+ _gated_load_fakes(monkeypatch, short_fits = [1])
+ monkeypatch.setattr(inf, "_free_for_chat", free := AsyncMock(return_value = []))
+ request = LoadRequest(model_path = "org/C-GGUF", alongside = True)
+ run_as(BESIDE_ONLY, asyncio.run, inf.load_model_gated(request, None, "s", background = True))
+ assert [call.kwargs["media_only"] for call in free.await_args_list] == [True]
+
+
+def test_beside_only_and_measured_always_refusals_unload_nothing_and_name_no_model():
+ # The beside-only refusal comes before vLLM or SGLang retires every kept model.
+ source = inspect.getsource(inf._load_model_impl)
+ refuse = source.index("_require_load_keeps_chat(fastapi_request, request)")
+ assert refuse < source.index("_gate_kept_models(request, cancel = False)")
+ # No kind: it would read as the model to unload, but an image or video model may hold the GPU.
+ source = inspect.getsource(inf.load_model_gated)
+ assert "raise MultiModelAlwaysRefusal(str(exc)) from exc" in source
+
+
def _short_load_fakes(monkeypatch, errors):
monkeypatch.setattr(inf, "release_chat_gpu_claim", lambda: None)
seen = []
@@ -1879,3 +1944,41 @@ def test_an_unattended_load_that_fits_beside_the_primary_is_not_rechecked(backen
)
assert primary.model_identifier == "org/A-GGUF"
assert model_slots.slots[-1].request.model_path == "org/C-GGUF"
+
+
+def test_long_narration_is_budgeted_against_the_kept_speech_model_not_the_chat_primary(monkeypatch):
+ from models.inference import ChatCompletionRequest
+
+ kept = object()
+
+ class Reached(Exception):
+ pass
+
+ async def route(workflow):
+ inf.routed_slot.set(kept)
+
+ async def no_switch(*a, **kw):
+ return None
+
+ def no_further(*a, **kw):
+ raise Reached
+
+ # The chat primary has a 64-token context; the kept speech model takes the narration.
+ monkeypatch.setattr(inf, "_serves_audio_workflow", lambda workflow: False)
+ monkeypatch.setattr(inf, "_maybe_auto_switch_model", no_switch)
+ monkeypatch.setattr(inf, "_route_to_kept_audio_model", route)
+ monkeypatch.setattr(
+ inf, "_monitor_context_length", lambda: 8192 if inf.routed_slot.get() is kept else 64
+ )
+ monkeypatch.setattr(inf, "_audio_run_event", no_further)
+ payload = ChatCompletionRequest(messages = [{"role": "user", "content": "x"}])
+
+ async def run():
+ token = inf.routed_slot.set(None)
+ try:
+ await inf._generate_tts_wav("word " * 400, payload, request = None, current_subject = "t")
+ finally:
+ inf.routed_slot.reset(token)
+
+ with pytest.raises(Reached):
+ asyncio.run(run())
diff --git a/studio/backend/tests/test_music_beside_chat.py b/studio/backend/tests/test_music_beside_chat.py
new file mode 100644
index 00000000000..c3deada78c7
--- /dev/null
+++ b/studio/backend/tests/test_music_beside_chat.py
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""An audio model kept beside the chat model runs its workflow, as far as its generate call."""
+
+import asyncio
+from dataclasses import replace
+
+import pytest
+
+import core.inference.model_slots as model_slots
+import core.inference.orchestrator as orchestrator
+import routes.inference as inf
+from core.inference.load_policy import LoadPolicy
+from models.inference import AudioRunRequest, ChatCompletionRequest
+from studio.backend.tests.test_audio_run_route import _music_info, _speak_info
+from studio.backend.tests.test_multi_model_serving import FakeLlama, FakeOrchestrator
+from utils import multi_model_settings, openai_auto_switch_settings
+from utils.account_context import OWNER, run_as
+
+ACE_STEP = "audio-cpp/audio.cpp-gguf/ACE-Step1.5-GGUF"
+_INFO = {ACE_STEP: _music_info, "org/Music": _music_info, "org/Speech": _speak_info}
+_OWNER_CHAT_TOOLS_KEY = replace(
+ OWNER, via_api_key = True, load_policy = LoadPolicy.BESIDE_ONLY, ui_chat = True
+)
+
+
+class AudioOrchestrator(FakeOrchestrator):
+ """Loads ``model`` (music unless told); its generate call records itself and stops the run."""
+
+ generated: list = []
+
+ def load(self, model = ACE_STEP):
+ self.active_model_name, self.models = model, {model: _INFO[model]()}
+
+ def generate_audio_response(self, **_kwargs):
+ AudioOrchestrator.generated.append(self)
+ raise RuntimeError("stop")
+
+
+async def _load(*_a, **_kw):
+ inf.get_inference_backend().load()
+
+
+def _run(workflow, model = None):
+ if workflow == "music":
+ body = AudioRunRequest(workflow = "music", mode = "song", text = "lofi", model = model)
+ run = inf._run_music_workflow(body, None, "s")
+ else:
+ payload = ChatCompletionRequest(messages = [{"role": "user", "content": "hello"}])
+ run = inf._generate_tts_wav("hello", payload, None, "s")
+ with pytest.raises(Exception): # the stub stops every run that gets this far
+ run_as(_OWNER_CHAT_TOOLS_KEY, asyncio.run, run)
+
+
+def test_audio_loads_beside_chat_then_an_omitted_model_runs_on_the_one_kept_for_it(monkeypatch):
+ kept = [model_slots.ExtraSlot(FakeLlama(), AudioOrchestrator(), "owner") for _ in range(2)]
+ for slot, model in zip(kept, ["org/Music", "org/Speech"]):
+ slot.orchestrator.load(model)
+ for mod, name, value in [
+ (inf, "_llama_cpp_backend", FakeLlama("unsloth/Qwen-GGUF", "Q4_K_M")),
+ (orchestrator, "_inference_backend", FakeOrchestrator()),
+ (model_slots, "slots", kept),
+ (AudioOrchestrator, "generated", []),
+ (inf, "InferenceOrchestrator", AudioOrchestrator),
+ (inf, "_run_tracked_load_model_impl", _load),
+ (inf, "_target_speech_audio_type", lambda *_a: "audiocpp_music"),
+ (inf, "_target_audio_workflows", lambda *_a: {"music"}),
+ (inf, "_audio_cpp_switch_target", {ACE_STEP: (ACE_STEP, "Q8_0", ACE_STEP, False)}.get),
+ (multi_model_settings, "get_multi_model_enabled", lambda: True),
+ (multi_model_settings, "get_multi_model_mode", lambda: "always"),
+ (openai_auto_switch_settings, "get_openai_auto_switch_enabled", lambda: False),
+ ]:
+ monkeypatch.setattr(mod, name, value)
+ # Loads beside; its TTS step, which names no model, stays on it ("No model loaded." before).
+ _run("music", ACE_STEP)
+ _run("music") # two music models kept: the caller names one
+ _run("speak")
+ assert AudioOrchestrator.generated == [model_slots.slots[2].orchestrator, kept[1].orchestrator]
diff --git a/studio/backend/tests/test_openai_audio_speech_route.py b/studio/backend/tests/test_openai_audio_speech_route.py
index 2aac763612e..a1ad6114721 100644
--- a/studio/backend/tests/test_openai_audio_speech_route.py
+++ b/studio/backend/tests/test_openai_audio_speech_route.py
@@ -282,6 +282,8 @@ def test_only_resident_requests_use_the_pre_switch_budget(monkeypatch, named):
monkeypatch.setattr(routes_module, "_maybe_auto_switch_model", _switch)
monkeypatch.setattr(routes_module, "_monitor_context_length", lambda: 2048)
monkeypatch.setattr(routes_module, "_prompt_token_estimate", lambda _t: 2048)
+ # The resident model is a speech model, so an unnamed request is answered by it.
+ monkeypatch.setattr(routes_module, "_serves_audio_workflow", lambda _w: True)
payload = SimpleNamespace(audio_instructions = None, audio_language = None)
request = SimpleNamespace(state = SimpleNamespace(skip_api_monitor = True))
model = "org/B-GGUF" if named else routes_module._RELOAD_ONLY_MODEL
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 06d4f2128ba..2b38f907328 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -9,6 +9,8 @@ import os
import threading
import time
import types
+from dataclasses import replace
+from unittest.mock import AsyncMock
import pytest
from fastapi import HTTPException
@@ -17,6 +19,7 @@ import routes.inference as inference_route
from models.inference import LoadRequest
from core.inference import local_model_resolver as resolver
from utils import openai_auto_switch_settings as settings
+from utils.account_context import OWNER, AccountContext, run_as
from core.inference import llama_cpp as llama_cpp_mod
from core.inference import llama_keepwarm as kw
from core.inference.llama_cpp import LlamaCppBackend
@@ -294,6 +297,68 @@ def test_already_loaded_does_not_reload(monkeypatch):
assert rec.calls == []
+def _as_chat_tools_key(account, fn, *args, **kwargs):
+ if account is None:
+ return fn(*args, **kwargs)
+ key = replace(account, via_api_key = True, load_policy = "beside_only", ui_chat = True)
+ return run_as(key, fn, *args, **kwargs)
+
+
+def test_a_chat_tools_key_never_replaces_the_loaded_model(monkeypatch):
+ monkeypatch.setattr("utils.multi_model_settings.get_multi_model_enabled", lambda: False)
+ b = ("unsloth/B-GGUF", "Q4_K_M", "unsloth/B-GGUF")
+ backend, rec = _wired(monkeypatch, _FakeBackend("unsloth/A-GGUF"), b)
+ with pytest.raises(HTTPException) as excinfo:
+ _as_chat_tools_key(OWNER, _run_hook, "unsloth/B-GGUF:Q4_K_M")
+ assert excinfo.value.headers["X-Unsloth-Problem"].startswith("needs_user_load kind=llm")
+ assert rec.calls == [] and backend.model_identifier == "unsloth/A-GGUF"
+ _run_hook("unsloth/B-GGUF:Q4_K_M") # any other credential still switches
+ assert len(rec.calls) == 1
+
+
[email protected]("mode, enabled", [("always", True), ("always", False), ("off", True)])
+def test_a_chat_tools_key_loads_music_beside_the_chat_model_even_with_switch_off_or_says_why(
+ monkeypatch, mode, enabled
+):
+ monkeypatch.setattr("utils.multi_model_settings.get_multi_model_enabled", lambda: mode != "off")
+ monkeypatch.setattr("utils.multi_model_settings.get_multi_model_mode", lambda: mode)
+ music = ("org/Music-GGUF", "Q4_K_M", "org/Music-GGUF")
+ backend, rec = _wired(monkeypatch, _FakeBackend("unsloth/A-GGUF"), music, enabled = enabled)
+ backend.is_active, backend._is_audio = True, False
+ gated = AsyncMock(side_effect = _Reached())
+ monkeypatch.setattr(inference_route, "load_model_gated", gated)
+ monkeypatch.setattr(inference_route, "_target_speech_audio_type", lambda *_a: "music_type")
+ monkeypatch.setattr(inference_route, "_target_audio_workflows", lambda *_a: {"music"})
+ with pytest.raises(HTTPException if mode == "off" else _Reached) as excinfo:
+ _as_chat_tools_key(OWNER, _run_hook, "org/Music-GGUF:Q4_K_M", **_MUSIC_RUN)
+ assert rec.calls == [] and backend.model_identifier == "unsloth/A-GGUF"
+ assert [c.args[0].alongside for c in gated.await_args_list] == ([] if mode == "off" else [True])
+ if mode == "off":
+ problem = excinfo.value.headers["X-Unsloth-Problem"]
+ assert problem == "needs_user_load kind=audio model=org/Music-GGUF:Q4_K_M page=Audio"
+ assert "Keep multiple models loaded" in excinfo.value.detail # the reason, for the user
+
+
+AUDIO_CPP_MUSIC = "audio-cpp/audio.cpp-gguf/Stable-Audio-3-Small-Music-GGUF"
+_MUSIC_RUN = dict(claim_resident = False, require_speech = True, require_audio_workflow = "music")
+
+
+ "account, problem",
+ [
+ (None, f"not_loaded kind=audio model={AUDIO_CPP_MUSIC} page=Audio"),
+ (OWNER, "needs_download kind=audio model=audio-cpp/"), # not on disk: not "would unload"
+ (AccountContext("acct-alice", "alice"), "needs_user_load kind=audio"), # needs the switch
+ ],
+)
+def test_switch_off_refuses_an_audio_cpp_model_that_is_not_loaded(monkeypatch, account, problem):
+ backend, rec = _wired(monkeypatch, _FakeBackend("unsloth/A-GGUF"), None, enabled = False)
+ monkeypatch.setattr(inference_route.account_access, "managed_account", lambda: False)
+ with pytest.raises(HTTPException) as excinfo:
+ _as_chat_tools_key(account, _run_hook, AUDIO_CPP_MUSIC, **_MUSIC_RUN)
+ assert excinfo.value.headers["X-Unsloth-Problem"].startswith(problem) and rec.calls == []
+
+
def test_known_unloaded_model_switches_once(monkeypatch):
backend, rec = _wired(
monkeypatch, _FakeBackend("unsloth/A-GGUF"), ("unsloth/B-GGUF", "Q4_K_M", "unsloth/B-GGUF")
@@ -12464,6 +12529,21 @@ def test_an_npu_model_named_by_a_request_switches_when_on(monkeypatch):
assert [call.model_path for call in rec.calls] == [_NPU_MODEL]
+def test_a_chat_model_that_lands_before_the_npu_gates_still_refuses_a_chat_tools_switch(
+ monkeypatch,
+):
+ backend, rec = _wired(monkeypatch, _FakeBackend("unsloth/A-GGUF"), None)
+ # The preflight sees no chat model; one is resident by the time the swap gates are held.
+ checks: list = []
+ monkeypatch.setattr(
+ inference_route, "_chat_model_resident", lambda **_kw: checks.append(1) or len(checks) > 1
+ )
+ with pytest.raises(HTTPException) as excinfo:
+ _as_chat_tools_key(OWNER, _run_hook, _NPU_MODEL, serves_npu = True)
+ assert excinfo.value.headers["X-Unsloth-Problem"].startswith("needs_user_load kind=llm")
+ assert rec.calls == [] and len(checks) == 2
+
+
def test_an_npu_switch_loads_with_the_saved_context_length(monkeypatch):
backend, rec = _wired(monkeypatch, _FakeBackend("unsloth/A-GGUF"), None)
monkeypatch.setattr(
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 487d4e53f1e..301852733e9 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -38,6 +38,9 @@ def _no_host_default_hf_cache(monkeypatch, tmp_path):
):
monkeypatch.setattr(utils.paths, name, lambda: [])
monkeypatch.chdir(tmp_path)
+ # Module state an earlier test may leave: its media picks and a resident image or video engine.
+ monkeypatch.setattr(inf, "_MEDIA_PICK_CACHE", {"at": None, "picks": {}})
+ monkeypatch.setattr(inf, "_resident_media_status", lambda task: None)
class _Info:
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index d2e0be8d208..5a0f690e53c 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -2626,6 +2626,35 @@ class TestLoopBehaviour:
assert exec_fn.calls == [("python", {"code": "print(1)"})] * (1 if deduplicate else 2)
+ def test_two_identical_unseeded_studio_generations_in_one_turn_both_run(self):
+ from core.inference import tool_facts
+
+ name = "mcp__unsloth__generate_image"
+ tool_facts.note_mcp_tool(name, {"name": "generate_image"}, studio = True)
+ call = '<tool_call>{"name":"%s","arguments":{"prompt":"a cat"}}</tool_call>' % name
+ turns = iter([[call * 2], ["final"]])
+
+ def fake_single_turn(messages, active_tools = None):
+ acc = ""
+ for chunk in next(turns):
+ acc += chunk
+ yield acc
+
+ exec_fn = FakeExecuteTool(["img1", "img2"])
+ _collect_events(
+ run_safetensors_tool_loop(
+ single_turn = fake_single_turn,
+ messages = [{"role": "user", "content": "two cats"}],
+ tools = [{"type": "function", "function": {"name": name}}],
+ execute_tool = exec_fn,
+ max_tool_iterations = 4,
+ deduplicate_tool_calls = True,
+ )
+ )
+ tool_facts.note_mcp_tool(name, {"name": "generate_image"})
+
+ assert exec_fn.calls == [(name, {"prompt": "a cat"})] * 2
+
def test_duplicate_tool_call_internal_noop_allows_distinct_followup_tool(self):
captured_messages: list[list[dict]] = []
captured_tool_names: list[list[str]] = []
diff --git a/studio/backend/tests/test_studio_tools_chat.py b/studio/backend/tests/test_studio_tools_chat.py
new file mode 100644
index 00000000000..d8661bee296
--- /dev/null
+++ b/studio/backend/tests/test_studio_tools_chat.py
@@ -0,0 +1,737 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The chat's "Unsloth Studio" MCP row: the /mcp tools minus the chat denylist, called in process as
+the chat's own account through a per-call internal key, against a fake Studio behind the real auth."""
+
+import asyncio
+import json
+import sqlite3
+import threading
+import time
+from datetime import datetime, timedelta
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi import Depends, FastAPI, Request
+from fastapi.responses import JSONResponse, PlainTextResponse, Response
+from fastapi.testclient import TestClient
+from fastmcp.server.dependencies import _current_http_request
+from starlette.requests import Request as StarletteRequest
+
+from auth import storage
+from auth.authentication import get_current_subject
+from auth.policy import OwnerOnly
+from core.inference import mcp_client, media_chat_tools, studio_tools_mcp
+from core.inference import tools as tools_mod
+from mcp_server import create_studio_mcp, withheld
+from storage import mcp_servers_db
+from studio_mcp import caller as caller_mod
+from studio_mcp import forward as forward_mod
+from studio_mcp.inputs import PATH_REMOTE
+from studio_mcp.profile import CHAT
+from utils import mcp_access
+from utils.account_context import OWNER, AccountContext, as_api_caller, current_account, run_as
+
+from .mcp_harness import (
+ MCP_HEADERS,
+ PNG,
+ SENTINEL_ROOTS,
+ WAV,
+ isolated_auth, # noqa: F401 (fixture)
+ make_caller,
+ poison,
+ seed_owner,
+)
+from .test_mcp_tools_training import RUN_PAYLOADS
+
+CHAT_WITHHELD = frozenset(withheld())
+URL = studio_tools_mcp.STUDIO_TOOLS_MCP_URL
+RUNS = ("GET", "/api/train/runs")
+KEY_NAME = storage.STUDIO_CHAT_TOOLS_KEY_NAME
+CANCELLED = "Error: MCP tool 'list_training_runs' cancelled"
+pytestmark = pytest.mark.usefixtures("isolated_auth", "studio_home")
+
+
+def studio_home(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))
+ monkeypatch.setattr(mcp_servers_db, "_schema_ready", set())
+ monkeypatch.setattr(mcp_client, "_tool_cache", {})
+ monkeypatch.setattr(mcp_client, "_probe_cooloff_until", {})
+ seed_owner()
+
+
+def server_loop(monkeypatch):
+ """Stands in for Unsloth Studio's own event loop, which the chat tool loop hands work to."""
+ loop = asyncio.new_event_loop()
+ thread = threading.Thread(target = loop.run_forever, daemon = True)
+ thread.start()
+ monkeypatch.setattr(media_chat_tools, "_server_loop", loop)
+ yield loop
+ loop.call_soon_threadsafe(loop.stop)
+ thread.join(5)
+
+
+def alice():
+ row = storage.issue_account_setup_code(username = "alice")["account"]
+ return AccountContext(row["account_id"], "alice", "user")
+
+
+def studio(monkeypatch, routes, *owner_only):
+ """A fake Studio behind the real auth dependency; ``app.state.seen`` records who each route ran as."""
+ app = FastAPI()
+ app.state.server_port, app.state.cloudflare_url, app.state.seen = 8888, None, []
+
+ def bind(method, path, answer):
+ async def endpoint(request: Request) -> Response:
+ token = request.headers["authorization"].removeprefix("Bearer ")
+ app.state.seen.append({"path": path, "account": current_account(), "token": token})
+ result = await answer(request) if callable(answer) else answer
+ return result if isinstance(result, Response) else JSONResponse(result)
+
+ deps = [Depends(get_current_subject)] + ([OwnerOnly] if path in owner_only else [])
+ app.add_api_route(path, endpoint, methods = [method], dependencies = deps)
+
+ for (method, path), answer in routes.items():
+ bind(method, path, answer)
+ monkeypatch.setattr(studio_tools_mcp, "_studio_app", app)
+ return app
+
+
+def bridge(account, name, *args, **kw):
+ return run_as(account, studio_tools_mcp.call, name, *(args or [{}]), **{"timeout": 30.0, **kw})
+
+
+def runs(account = OWNER, **kw):
+ return bridge(account, "list_training_runs", **kw)
+
+
+def call_tool_sync(**kw):
+ call, kw = mcp_client.call_tool_sync, {"timeout": 30.0, **kw}
+ return run_as(OWNER, call, URL, None, "list_training_runs", {}, **kw)
+
+
+def minted_keys(monkeypatch):
+ rows, real = [], storage.create_api_key
+
+ def spy(*args, **kwargs):
+ key, row = real(*args, **kwargs)
+ if kwargs.get("name") == KEY_NAME:
+ rows.append(dict(row, is_internal = bool(kwargs.get("internal"))))
+ return key, row
+
+ monkeypatch.setattr(storage, "create_api_key", spy)
+ return rows
+
+
+def chat_keys():
+ """Chat tools key rows left in either key table: the bridge deletes them when its call ends."""
+ conn = sqlite3.connect(storage.DB_PATH)
+ try:
+ tables = ("api_keys", "account_api_keys")
+ query = " UNION ALL ".join(f"SELECT id FROM {t} WHERE name = ?1" for t in tables)
+ return conn.execute(query, (KEY_NAME,)).fetchall()
+ finally:
+ conn.close()
+
+
+def add_row(account, **fields):
+ from models.mcp_servers import McpServerCreate
+ from routes.mcp_servers import create_mcp_server
+
+ payload = McpServerCreate(display_name = "Unsloth Studio", url = URL, **fields)
+ create = create_mcp_server(payload, current_subject = account.username)
+ return run_as(account, asyncio.run, create)
+
+
+def listed(account):
+ tools = run_as(account, asyncio.run, tools_mod.get_enabled_mcp_tools())
+ return [tool["function"]["name"] for tool in tools]
+
+
+def chat_tool_names():
+ return [tool.name for tool in asyncio.run(studio_tools_mcp.chat_tools_mcp().list_tools())]
+
+
+def test_the_reserved_url_is_port_agnostic_and_matches_the_frontend():
+ assert URL == "http://127.0.0.1/mcp/studio-tools"
+ ok = (URL, URL + "/", "http://localhost:8888/mcp/studio-tools")
+ for url in ok + ("http://[::1]:1/mcp/studio-tools",):
+ assert mcp_client.is_studio_tools(url) and not mcp_client.is_studio_decisions(url), url
+ bad = ("https://127.0.0.1/mcp/studio-tools", "http://192.168.1.2/mcp/studio-tools")
+ bad += ("http://127.0.0.1/mcp/studio-tools/x", "http://127.0.0.1/mcp")
+ for url in bad + ("http://[::1/mcp/studio-tools", "npx some-server"):
+ assert not mcp_client.is_studio_tools(url), url
+ source = Path(__file__).resolve().parents[2] / "frontend/src/features/chat/mcp-server-url.ts"
+ assert f'export const UNSLOTH_STUDIO_TOOLS_MCP_URL = "{URL}";' in source.read_text("utf-8")
+
+
+def test_the_chat_instance_drops_exactly_the_withheld_tools():
+ everything = [tool.name for tool in asyncio.run(create_studio_mcp().list_tools())]
+ loading = {"load_model", "unload_model", "plan_load"}
+ jobs = {"start_training", "export_model", "run_recipe"}
+ assert CHAT_WITHHELD == {"chat", "cancel"} | loading | jobs
+ assert chat_tool_names() == [name for name in everything if name not in CHAT_WITHHELD]
+ assert studio_tools_mcp.chat_tools_mcp() is studio_tools_mcp.chat_tools_mcp()
+
+
+def test_the_row_lists_chat_tools_fresh_every_send_minus_disabled_ones(
+ alice, server_loop, monkeypatch
+):
+ app = studio(monkeypatch, RUN_PAYLOADS)
+ probes, real_probe = [], tools_mod.list_tools_async
+ monkeypatch.setattr(tools_mod, "list_tools_async", lambda **kw: probes.append(kw))
+ assert listed(alice) == []
+ add_row(alice, is_enabled = False)
+ assert listed(alice) == [] and probes == []
+ monkeypatch.setattr(tools_mod, "list_tools_async", real_probe)
+ prefix = f"mcp__{add_row(alice).id}__"
+ names = listed(alice)
+ assert sorted(names) == sorted(prefix + name for name in chat_tool_names())
+ keyless = as_api_caller(alice)
+ assert listed(keyless) == [] and run_as(keyless, tools_mod.cached_mcp_tools)[0] == []
+ mcp_access.set_mcp_settings(disabled_tools = ["list_training_runs"])
+ assert prefix + "list_training_runs" not in listed(alice)
+ assert "[tool_disabled]" in runs(alice) and app.state.seen == []
+ mcp_access.set_mcp_settings(disabled_tools = [])
+ assert "qwen-lora" in runs(alice)
+ narrower = create_studio_mcp(CHAT, exclude = frozenset({"list_models"}))
+ monkeypatch.setattr(studio_tools_mcp, "_mcp", narrower)
+ assert sorted(listed(alice)) == sorted(set(names) - {prefix + "list_models"})
+
+
+def test_a_call_runs_as_the_owner_through_the_bridge_with_a_deleted_short_lived_key(
+ server_loop, monkeypatch
+):
+ app = studio(monkeypatch, RUN_PAYLOADS)
+ minted = minted_keys(monkeypatch)
+
+ def no_session(*a, **k):
+ raise AssertionError("the Unsloth Studio tools row must not use a pooled session")
+
+ monkeypatch.setattr(mcp_client, "_call_session_tool", no_session)
+ result = call_tool_sync(timeout = None, scope = "thread:1")
+ assert "qwen-lora" in result and not result.startswith("Error"), result
+ assert ":null" not in result and ": null" not in result, result
+ (seen,), (key,) = [e for e in app.state.seen if e["path"] == RUNS[1]], minted
+ assert seen["account"].is_owner and key["is_internal"] and chat_keys() == []
+ # A timeout of None waits up to an hour; the key outlives that only by its grace, never 6 h.
+ lifetime = datetime.fromisoformat(key["expires_at"]) - datetime.fromisoformat(key["created_at"])
+ assert timedelta(minutes = 64) < lifetime <= timedelta(minutes = 65)
+ assert storage.validate_api_key_account(seen["token"], touch = False) is None
+ _key, row = studio_tools_mcp._mint(OWNER, 10 * 24 * 3600.0)
+ lifetime = datetime.fromisoformat(row["expires_at"]) - datetime.fromisoformat(row["created_at"])
+ assert lifetime <= timedelta(hours = 6)
+
+
+def test_each_account_runs_as_itself_even_at_once(alice, server_loop, monkeypatch):
+ both_in, arrived, results = asyncio.Event(), [], []
+
+ async def rendezvous(request):
+ arrived.append(1)
+ if len(arrived) == 2:
+ both_in.set()
+ await asyncio.wait_for(both_in.wait(), 10)
+ return RUN_PAYLOADS[RUNS]
+
+ app = studio(monkeypatch, {**RUN_PAYLOADS, RUNS: rendezvous})
+ run = lambda account: results.append(runs(account))
+ threads = [threading.Thread(target = run, args = (account,)) for account in (OWNER, alice)]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join(20)
+ assert len(results) == 2 and all("qwen-lora" in result for result in results), results
+ by_token = {}
+ for entry in app.state.seen:
+ by_token.setdefault(entry["token"], set()).add(entry["account"].account_id)
+ assert sorted(map(sorted, by_token.values())) == sorted([["owner"], [alice.account_id]])
+ studio(monkeypatch, RUN_PAYLOADS, "/api/train/runs")
+ assert "installation owner" in runs(alice) and chat_keys() == []
+
+
+def test_stop_cancels_the_route_and_an_image_render_on_the_gpu(alice, server_loop, monkeypatch):
+ from core.inference.generation_ticket import bind_generation_cancel
+
+ cancelled, render, bound = threading.Event(), threading.Event(), threading.Event()
+
+ async def blocking(request):
+ try:
+ bound.set()
+ await asyncio.sleep(30)
+ except asyncio.CancelledError:
+ cancelled.set()
+ raise
+
+ def engine():
+ bind_generation_cancel(render)
+ bound.set()
+ render.wait(10)
+
+ async def generating(request):
+ await asyncio.to_thread(engine)
+ return RUN_PAYLOADS[RUNS]
+
+ for answer, done in ((blocking, cancelled), (generating, render)):
+ studio(monkeypatch, {**RUN_PAYLOADS, RUNS: answer})
+ bound.clear()
+ stop = threading.Event()
+ # Stop once the route is running: a fixed delay can fire before a loaded host reaches it.
+ threading.Thread(target = lambda: bound.wait(10) and stop.set(), daemon = True).start()
+ started = time.monotonic()
+ assert runs(alice, cancel_event = stop) == CANCELLED
+ assert time.monotonic() - started < 10 and chat_keys() == []
+ assert done.wait(5)
+
+
+def test_stop_while_polling_stops_a_render_an_earlier_call_of_the_turn_started(
+ alice, server_loop, monkeypatch
+):
+ from core.inference.generation_ticket import bind_generation_cancel
+
+ # generate_video binds its job's cancel and returns at once; get_job then polls it.
+ renders, bound = [], threading.Event()
+
+ async def starts_a_render(request):
+ renders.append(threading.Event())
+ await asyncio.to_thread(bind_generation_cancel, renders[-1])
+ return RUN_PAYLOADS[RUNS]
+
+ async def polling(request):
+ bound.set()
+ await asyncio.sleep(30)
+
+ turn, other_turn = threading.Event(), threading.Event()
+ studio(monkeypatch, {**RUN_PAYLOADS, RUNS: starts_a_render})
+ assert "qwen-lora" in runs(alice, cancel_event = turn)
+ assert "qwen-lora" in runs(alice, cancel_event = other_turn)
+ studio(monkeypatch, {**RUN_PAYLOADS, RUNS: polling})
+ # A poll that only times out leaves the render running.
+ assert "timed out" in runs(alice, cancel_event = turn, timeout = 1.0)
+ assert not any(render.is_set() for render in renders)
+ threading.Thread(target = lambda: bound.wait(10) and turn.set(), daemon = True).start()
+ assert runs(alice, cancel_event = turn) == CANCELLED
+ video, other_video = renders
+ assert video.wait(5) and chat_keys() == []
+ assert not other_video.is_set()
+
+
[email protected]("untracked", [False, True])
+def test_the_route_discounts_the_calling_chat_only_when_it_is_counted(
+ server_loop, monkeypatch, untracked
+):
+ from core.inference import llama_keepwarm, load_policy
+
+ seen = []
+
+ async def reads_the_marker(request):
+ seen.append(load_policy.parent_chat_counted())
+ return RUN_PAYLOADS[RUNS]
+
+ studio(monkeypatch, {**RUN_PAYLOADS, RUNS: reads_the_marker})
+ # The chat's own scope, as the keep-warm middleware leaves it; an external-provider chat untracks itself.
+ scope = {llama_keepwarm._TRACKED_SCOPE_KEY: True}
+ if untracked:
+ scope[llama_keepwarm._UNTRACKED_SCOPE_KEY] = True
+ token = llama_keepwarm._current_response_scope.set(scope)
+ try:
+ assert "qwen-lora" in runs()
+ finally:
+ llama_keepwarm._current_response_scope.reset(token)
+ assert seen == [not untracked] and load_policy._counted_parents == set()
+
+
+async def _hang(request):
+ await asyncio.sleep(30)
+
+
+ "answer, timeout, expected",
+ [
+ (_hang, 1.0, "Error: MCP tool 'list_training_runs' timed out after 1s"),
+ (JSONResponse({"detail": "boom"}, status_code = 500), 30.0, "Error: "),
+ ],
+)
+def test_a_timeout_or_error_deletes_the_key(server_loop, monkeypatch, answer, timeout, expected):
+ studio(monkeypatch, {**RUN_PAYLOADS, RUNS: answer})
+ assert runs(timeout = timeout).startswith(expected)
+ assert chat_keys() == []
+
+
+def _stop_during_mint(monkeypatch, alice):
+ stop, real = threading.Event(), studio_tools_mcp._mint
+ monkeypatch.setattr(studio_tools_mcp, "_mint", lambda *a: (real(*a), stop.set())[0])
+ return lambda: runs(cancel_event = stop)
+
+
+def _inactive(monkeypatch, alice):
+ storage.set_account_active(alice.account_id, False)
+ return lambda: runs(alice)
+
+
+def _password_reset(monkeypatch, alice):
+ generation = storage.credential_generation(storage.get_user_record("unsloth")["jwt_secret"])
+ account = AccountContext(OWNER.account_id, OWNER.username, OWNER.role, generation)
+ assert account == OWNER and "qwen-lora" in runs(account), "the current generation mints"
+ storage.update_password("unsloth", "a-new-password-123", revoke_refresh_tokens = True)
+ return lambda: runs(account)
+
+
+def _stale_row(*checks):
+ def scenario(monkeypatch, alice):
+ answers = iter(checks)
+ return lambda: call_tool_sync(config_check = lambda: next(answers))
+
+ return scenario
+
+
+def _withheld(name):
+ return lambda m, a: lambda: bridge(OWNER, name, {"model": "x", "config": {}, "messages": []})
+
+
+STOPPED, HOST_FILE = SimpleNamespace(is_set = lambda: True), {"audio": {"path": __file__}}
+REFUSED = [(f"withheld-{name}", "Unknown tool", _withheld(name)) for name in sorted(CHAT_WITHHELD)]
+REFUSED += [
+ ("keyless", "API key", lambda m, a: lambda: runs(as_api_caller(OWNER))),
+ ("inactive", "authorize", _inactive),
+ ("password-reset", "authorize", _password_reset),
+ (
+ "no-loop",
+ "not ready",
+ lambda m, a: m.setattr(media_chat_tools, "_server_loop", None) or runs,
+ ),
+ ("host-path", PATH_REMOTE, lambda m, a: lambda: bridge(OWNER, "transcribe", HOST_FILE)),
+ ("stopped-first", "cancelled", lambda m, a: lambda: runs(cancel_event = STOPPED)),
+ ("stopped-during-mint", "cancelled", _stop_during_mint),
+ ("stale-before-mint", "updated or removed", _stale_row(False)),
+ ("stale-after-mint", "updated or removed", _stale_row(True, False)),
+ ("stale-on-the-loop", "updated or removed", _stale_row(True, True, False)),
+]
+
+
+ "expected, scenario", [r[1:] for r in REFUSED], ids = [r[0] for r in REFUSED]
+)
+def test_a_refused_call_never_reaches_a_route_and_leaves_no_key(
+ alice, server_loop, monkeypatch, expected, scenario
+):
+ app = studio(monkeypatch, RUN_PAYLOADS)
+ invoke, sent = scenario(monkeypatch, alice), []
+ monkeypatch.setattr(forward_mod, "_send", lambda *a, **k: sent.append(a))
+ app.state.seen.clear()
+ result = invoke()
+ assert result.startswith("Error: ") and expected in result, result
+ assert app.state.seen == [] and sent == [] and chat_keys() == []
+
+
+def test_route_host_paths_do_not_reach_the_chat(server_loop, monkeypatch):
+ studio(monkeypatch, {route: poison(payload) for route, payload in RUN_PAYLOADS.items()})
+ result = bridge(OWNER, "list_training_runs", {"run_id": "run-1", "include_checkpoints": True})
+ assert "qwen-lora" in result
+ assert not any(root in result for root in SENTINEL_ROOTS), result
+
+
+def test_a_chat_tool_loads_only_beside_and_is_told_to_ask_the_user(server_loop, monkeypatch):
+ from core.inference.load_policy import current_load_policy
+
+ music, policies = "audio-cpp/audio.cpp-gguf/Stable-Audio-3-Small-Music-GGUF", []
+
+ async def not_loaded(_request):
+ policies.append(current_load_policy().value)
+ problem = f"not_loaded kind=audio model={music} page=Audio"
+ body = {"error": {"message": "Load a music model first.", "type": "x", "code": None}}
+ return JSONResponse(body, status_code = 400, headers = {"X-Unsloth-Problem": problem})
+
+ studio(monkeypatch, {("POST", "/v1/audio/run"): not_loaded})
+ result = bridge(OWNER, "generate_audio", {"workflow": "music", "text": "lofi", "model": music})
+ assert policies == ["beside_only"] and "[not_loaded kind=audio]" in result, result
+ assert "load_model" not in result and "unload_model" not in result
+ assert "on the Audio page in Unsloth Studio" in result
+
+
+def _http_request(caller = None):
+ state = {} if caller is None else {caller_mod.STATE_KEY: caller}
+ scope = {"type": "http", "method": "POST", "path": "/mcp/", "headers": [], "state": state}
+ return _current_http_request.set(StarletteRequest(scope))
+
+
+def test_an_http_request_never_sees_a_bound_caller():
+ bound = caller_mod.bind_caller(make_caller(token = "bound"))
+ try:
+ assert caller_mod.current_caller().token == "bound"
+ request = _http_request()
+ with pytest.raises(RuntimeError):
+ caller_mod.current_caller()
+ _current_http_request.reset(request)
+ request = _http_request(make_caller(token = "gate"))
+ assert caller_mod.current_caller().token == "gate"
+ _current_http_request.reset(request)
+ finally:
+ caller_mod.reset_caller(bound)
+
+
+def test_the_bridge_outranks_an_outer_http_request_and_unbinds_after(server_loop, monkeypatch):
+ app = studio(monkeypatch, RUN_PAYLOADS)
+ outer = _http_request(make_caller(token = "outer-agent-key"))
+ try:
+ assert "qwen-lora" in runs()
+ finally:
+ _current_http_request.reset(outer)
+ assert app.state.seen and "outer-agent-key" not in {entry["token"] for entry in app.state.seen}
+ with pytest.raises(RuntimeError):
+ caller_mod.current_caller()
+
+ async def on_the_loop():
+ return caller_mod._bound.get()
+
+ assert asyncio.run_coroutine_threadsafe(on_the_loop(), server_loop).result(5) is None
+
+
+def test_chat_works_with_agent_access_off_and_its_key_cannot_use_mcp(server_loop, monkeypatch):
+ from main import app as main_app
+
+ app = studio(monkeypatch, RUN_PAYLOADS)
+ revoked = []
+ monkeypatch.setattr(studio_tools_mcp, "_revoke", revoked.append)
+ mcp_access.set_mcp_enabled(False)
+ http = TestClient(main_app)
+ listing = {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+ assert http.post("/mcp/", json = listing, headers = MCP_HEADERS).status_code == 404
+ assert "qwen-lora" in runs()
+ mcp_access.set_mcp_enabled(True)
+ headers = {**MCP_HEADERS, "Authorization": f"Bearer {app.state.seen[0]['token']}"}
+ refused = http.post("/mcp/", json = listing, headers = headers)
+ assert refused.status_code == 401
+ assert refused.json() == {"detail": "Workflow keys cannot use Unsloth Studio MCP"}
+ (key,) = [k for k in storage.list_api_keys("unsloth", True) if k["name"] == KEY_NAME]
+ assert revoked == [key["id"]]
+ storage.revoke_internal_api_key(key["id"])
+
+
+def test_a_structured_call_outside_the_bridge_has_no_caller():
+ result = mcp_client.call_tool_structured_sync(URL, None, "studio_status", {}, timeout = 30.0)
+ assert result["is_error"] is True and chat_keys() == []
+
+
+def test_a_chat_request_with_mcp_remembers_the_server_loop(monkeypatch):
+ from routes import inference
+
+ async def no_tools(*a, **k):
+ return []
+
+ monkeypatch.setattr(media_chat_tools, "_server_loop", None)
+ monkeypatch.setattr(tools_mod, "get_enabled_mcp_tools", no_tools)
+ fields = ("enabled_tools", "rag_scope", "sandbox_level", "thread_id", "deep_research_armed")
+ payload = SimpleNamespace(bypass_permissions = False, **dict.fromkeys(fields))
+
+ async def select():
+ await inference._select_request_tools(payload, tools_on = False, mcp_allowed = True)
+ return asyncio.get_running_loop()
+
+ loop = asyncio.new_event_loop()
+ try:
+ assert loop.run_until_complete(select()) is media_chat_tools.server_loop()
+ finally:
+ loop.close()
+
+
+GALLERY, AUDIO = "/api/inference/images/gallery/img-1", "/v1/audio/gallery/clip-1"
+IMAGE = dict(id = "img-1", url = f"{GALLERY}/file", prompt = "a red fox", width = 64, height = 64)
+IMAGE.update(steps = 4, guidance = 0.0, seed = 1, model = "black-forest-labs/FLUX.1-schnell")
+CLIP = dict(id = "clip-1", url = f"{AUDIO}/file", duration_s = 1.0, sample_rate = 24000)
+CLIP.update(workflow = "speak", text = "hi", model = "m")
+
+
+async def _media(request):
+ is_png = request.url.path.startswith("/api")
+ return Response(PNG if is_png else WAV, media_type = "image/png" if is_png else "audio/wav")
+
+
+MEDIA_ROUTES = {
+ ("POST", "/api/inference/images/generate"): {"images": [IMAGE]},
+ ("GET", "/api/inference/images/generate-progress"): {"active": False},
+ ("GET", f"{GALLERY}/file"): _media,
+ ("GET", f"{GALLERY}/signed-url"): {"url": f"{GALLERY}/file-signed?token=t.img-1"},
+ ("POST", "/v1/audio/run"): {"clips": [CLIP], "group_id": None, "model": "m", "audio": None},
+ ("GET", f"{AUDIO}/file"): _media,
+ ("GET", f"{AUDIO}/signed-url"): {"url": f"{AUDIO}/file-signed?token=t.clip-1"},
+ ("GET", "/api/inference/status"): {"loaded": []},
+}
+LINK = {"prompt": "a red fox", "return_media": "link"}
+
+
+ "root, name, args, link",
+ [
+ ("", "generate_image", LINK, f"img-1.png: {GALLERY}/file-signed"),
+ ("/studio", "generate_image", LINK, f"img-1.png: /studio{GALLERY}/file-signed"),
+ ("", "generate_image", {"prompt": "a red fox"}, ""),
+ ("", "generate_audio", {"workflow": "speak", "text": "hi"}, f"clip-1.wav: {AUDIO}/"),
+ ],
+)
+def test_chat_media_links_are_origin_relative_text(
+ server_loop, monkeypatch, root, name, args, link
+):
+ # A ResourceLink needs an absolute URI and a chat call's links are origin-relative.
+ studio(monkeypatch, MEDIA_ROUTES)
+ callers, real = [], studio_tools_mcp._call
+ monkeypatch.setattr(
+ studio_tools_mcp, "_call", lambda c, *rest: callers.append(c) or real(c, *rest)
+ )
+ token = studio_tools_mcp._root_path.set(root)
+ try:
+ result = bridge(OWNER, name, args)
+ finally:
+ studio_tools_mcp._root_path.reset(token)
+ assert not result.startswith("Error") and link in result, result
+ (caller,) = callers
+ assert caller.public_base == root and caller.call_scoped and not caller.direct_local
+
+
+def test_the_middleware_hands_each_request_its_root_path():
+ inner = FastAPI()
+
+ @inner.get("/seen")
+ def seen():
+ return PlainTextResponse(studio_tools_mcp._root_path.get())
+
+ inner.add_middleware(studio_tools_mcp.ChatRootPathMiddleware)
+ with TestClient(inner, root_path = "/studio/") as http:
+ assert http.get("/seen").text == "/studio"
+ with TestClient(inner) as http:
+ assert http.get("/seen").text == ""
+ assert studio_tools_mcp._root_path.get() == ""
+
+
+def test_dropping_nulls_keeps_empty_lists_false_zero_and_recipe_rows():
+ from mcp.types import TextContent
+
+ def strip(texts, structured):
+ blocks = [TextContent(type = "text", text = text) for text in texts]
+ return studio_tools_mcp._without_nulls(
+ SimpleNamespace(content = blocks, structured_content = structured)
+ )
+
+ result = strip(
+ ['{"a":null,"b":[],"c":false,"d":0,"e":[{"f":null}]}', "not json {"],
+ {"a": None, "b": {"c": None, "d": 1}},
+ )
+ assert [block.text for block in result.content] == [
+ '{"b":[],"c":false,"d":0,"e":[{}]}',
+ "not json {",
+ ]
+ assert result.structured_content == {"b": {"d": 1}}
+ rows = [{"text": "x", "label": None}, {"text": "y", "label": None}]
+ result = strip(
+ [json.dumps({"status": "completed", "error": None, "data_rows": rows})],
+ {"error": None, "data_rows": rows},
+ )
+ assert json.loads(result.content[0].text) == {"status": "completed", "data_rows": rows}
+ assert result.structured_content == {"data_rows": rows}
+
+
+class _VideoReads:
+ """jobs.follow answers in order; each read records its arguments."""
+
+ def __init__(self, *answers):
+ self.answers, self.calls = list(answers), []
+
+ async def __call__(
+ self,
+ caller,
+ name,
+ job_id,
+ wait_s = 0,
+ **_kw,
+ ):
+ self.calls.append((name, job_id, wait_s))
+ answer = self.answers.pop(0)
+ if isinstance(answer, Exception):
+ raise answer
+ return answer
+
+
+def _job(status):
+ return SimpleNamespace(structured_content = {"kind": "video", "id": "video_1", "status": status})
+
+
+def _follow(monkeypatch, reads, created, seconds):
+ from studio_mcp import jobs
+ monkeypatch.setattr(jobs, "follow", reads)
+ return asyncio.run(
+ studio_tools_mcp._follow_video(object(), created, time.monotonic() + seconds)
+ )
+
+
+CREATED = SimpleNamespace(is_error = False, structured_content = {"id": "video_1", "status": "queued"})
+
+
+def test_a_chats_video_is_followed_to_the_end_inside_its_own_call(monkeypatch):
+ done = _job("completed")
+ reads = _VideoReads(_job("in_progress"), done)
+ assert _follow(monkeypatch, reads, CREATED, 600) is done
+ assert [(name, job) for name, job, _ in reads.calls] == [("video", "video_1")] * 2
+ assert all(0 < wait <= 240 for *_, wait in reads.calls)
+
+
+def test_following_a_video_falls_back_to_the_job_and_never_outlives_its_limit(monkeypatch):
+ from fastmcp.exceptions import ToolError
+
+ # A failed read: the job reference still answers.
+ assert _follow(monkeypatch, _VideoReads(ToolError("gone")), CREATED, 600) is CREATED
+ # Out of time: hand the job back, still running, rather than wait into the call's timeout.
+ late = _VideoReads()
+ assert _follow(monkeypatch, late, CREATED, 0) is CREATED and late.calls == []
+ # A refused create is not followed.
+ refused = SimpleNamespace(is_error = True, structured_content = None)
+ assert _follow(monkeypatch, _VideoReads(), refused, 600) is refused
+
+
+def test_a_video_still_rendering_when_its_call_returns_is_stopped_with_its_chat(monkeypatch):
+ from core.inference.generation_ticket import GenerationTicket
+
+ monkeypatch.setattr(studio_tools_mcp, "_WATCH_POLL_S", 0.05)
+ render, stop, ticket = threading.Event(), threading.Event(), GenerationTicket()
+ ticket.bind(render)
+ assert studio_tools_mcp._still_running(
+ SimpleNamespace(structured_content = {"status": "in_progress"})
+ )
+ assert not studio_tools_mcp._still_running(
+ SimpleNamespace(structured_content = {"status": "completed"})
+ )
+ studio_tools_mcp._watch_turn(stop, ticket)
+ time.sleep(0.2)
+ # The turn goes on (the model answers): the render keeps going.
+ assert not render.is_set()
+ stop.set()
+ assert render.wait(2)
+ # A stand-in event with no wait() is ignored rather than watched.
+ studio_tools_mcp._watch_turn(SimpleNamespace(is_set = lambda: True), GenerationTicket())
+
+
+ "name, status, watched",
+ [
+ ("generate_video", "queued", True),
+ ("generate_video", "completed", False),
+ ("list_training_runs", "queued", False),
+ ],
+)
+def test_only_a_chats_still_running_video_is_watched(
+ server_loop, monkeypatch, name, status, watched
+):
+ seen = []
+
+ async def answer(caller, tool, args, *_rest, **_kw):
+ return SimpleNamespace(content = [], structured_content = {"id": "v1", "status": status})
+
+ studio(monkeypatch, RUN_PAYLOADS)
+ monkeypatch.setattr(studio_tools_mcp, "_call", answer)
+ monkeypatch.setattr(studio_tools_mcp, "_watch_turn", lambda event, ticket: seen.append(event))
+ turn = threading.Event()
+ out = bridge(OWNER, name, {}, cancel_event = turn)
+ assert not out.startswith("Error") and seen == ([turn] if watched else []), out
diff --git a/studio/backend/tests/test_tool_loop_controller.py b/studio/backend/tests/test_tool_loop_controller.py
index 0a68bcba33b..e1ff85b4e57 100644
--- a/studio/backend/tests/test_tool_loop_controller.py
+++ b/studio/backend/tests/test_tool_loop_controller.py
@@ -36,6 +36,7 @@ from core.inference.tool_loop_controller import (
tool_call_limit_nudge,
tool_event_provenance,
)
+from core.inference import tool_facts
from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, parse_tool_calls_from_text
from core.inference.tools import (
ALL_TOOLS,
@@ -182,7 +183,7 @@ def test_successful_duplicate_is_internal_noop_and_keeps_remaining_tools():
)
assert "previous tool request" not in duplicate_nudge.lower()
assert "already completed successfully" in duplicate_nudge
- assert "different enabled tool" in duplicate_nudge
+ assert "call a different tool only if" in duplicate_nudge
assert completion.model_message()["role"] == "user"
_shared_setup_1(controller)
@@ -1007,6 +1008,52 @@ def test_a_hard_cap_below_the_window_cap_leaves_truncated_terminal_output_alone(
assert completion.tool_message()["content"] == already
+def test_a_read_only_mcp_result_is_not_new_work_until_its_hint_is_dropped():
+ status, models, generate = (f"mcp__unsloth__{n}" for n in ("status", "models", "generate"))
+ for name in (status, models, generate):
+ tool_facts.note_mcp_tool(name, {"annotations": {"readOnlyHint": name != generate}})
+ controller = ToolLoopController(tools = [_tool(status), _tool(models), _tool(generate)])
+ controller.record_result(controller.prepare_call(_call(status, {})), '{"chat":{}}')
+ controller.record_result(controller.prepare_call(_call(models, {})), '{"models":[]}')
+ duplicate = controller.prepare_call(_call(status, {}))
+ assert duplicate.action == "duplicate" and "Answer from the results" in duplicate.noop_result
+ controller.record_result(controller.prepare_call(_call(generate, {"text": "x"})), "Error: x")
+ assert controller.prepare_call(_call(status, {})).action == "execute"
+ tool_facts.note_mcp_tool(models, {"name": "models"})
+ assert not tool_facts.reads_only(models)
+
+
+def test_only_a_result_the_user_must_unblock_marks_the_turn_as_awaiting_them():
+ name = "mcp__unsloth__generate_audio"
+ controller = ToolLoopController(tools = [_tool(name)])
+ for model, result, awaiting in (
+ ("m", "Error: [needs_user_load kind=audio page=Audio] The music model is off.", True),
+ ("n", "Error: [not_loaded kind=audio] Load one with load_model(kind='tts') first.", False),
+ ("o", "Error: [not_loaded kind=audio] Ask the user to load one on the Audio page.", True),
+ (
+ "p",
+ "Error: [multi_model_always kind=chat] (HTTP 409) Call unload_model(kind='llm').",
+ False,
+ ),
+ ("q", "Error: [multi_model_always kind=chat] (HTTP 409) Ask the user to unload it.", True),
+ ):
+ controller.begin_batch()
+ controller.record_result(controller.prepare_call(_call(name, {"model": model})), result)
+ assert controller.awaiting_user is awaiting, result
+
+
+def test_a_refusal_the_user_must_unblock_survives_a_later_success_in_the_same_batch():
+ load, status = "mcp__unsloth__generate_audio", "mcp__unsloth__status"
+ controller = ToolLoopController(tools = [_tool(load), _tool(status)])
+ refusal = "Error: [needs_user_load kind=audio page=Audio] The music model is off."
+ controller.record_result(controller.prepare_call(_call(load, {"model": "m"})), refusal)
+ controller.record_result(controller.prepare_call(_call(status, {})), '{"chat":{}}')
+ assert controller.awaiting_user
+ controller.begin_batch()
+ controller.record_result(controller.prepare_call(_call(load, {"model": "n"})), "ok")
+ assert not controller.awaiting_user
+
+
def test_active_tools_are_private_copies_of_every_nested_schema_node():
"""Each call hands out its own copy: a caller rewriting one cannot reach the ledger or a later call."""
from collections import OrderedDict
@@ -1046,3 +1093,73 @@ def test_has_active_tools_matches_active_tools_without_copying():
controller._completed_one_shot_tools.clear()
controller._force_final_answer = True
assert controller.has_active_tools() is bool(controller.active_tools()) is False
+
+
+def test_polling_unsloths_own_get_job_is_never_a_duplicate():
+ video, job, status = (
+ f"mcp__unsloth__{n}" for n in ("generate_video", "get_job", "studio_status")
+ )
+ for name in (video, job, status):
+ tool_facts.note_mcp_tool(
+ name,
+ {"name": name.split("__")[2], "annotations": {"readOnlyHint": name != video}},
+ studio = True,
+ )
+ controller = ToolLoopController(tools = [_tool(video), _tool(job), _tool(status)])
+ poll = {"kind": "video", "id": "j1"}
+ controller.record_result(
+ controller.prepare_call(_call(video, {"prompt": "a whale"})), '{"id":"j1"}'
+ )
+ for name, args in ((job, poll), (status, {}), (job, poll), (job, poll)):
+ decision = controller.prepare_call(_call(name, args))
+ assert decision.action == "execute", name
+ controller.record_result(decision, '{"state":"running"}')
+ assert not controller.force_final_answer
+ # Another server's get_job is still deduplicated.
+ tool_facts.note_mcp_tool("mcp__other__get_job", {"name": "get_job"})
+ other = ToolLoopController(tools = [_tool("mcp__other__get_job")])
+ other.record_result(other.prepare_call(_call("mcp__other__get_job", poll)), "{}")
+ assert other.prepare_call(_call("mcp__other__get_job", poll)).action == "duplicate"
+
+
+def test_a_second_identical_generation_lets_the_gallery_be_read_again():
+ image, media = "mcp__unsloth__generate_image", "mcp__unsloth__list_media"
+ tool_facts.note_mcp_tool(image, {"name": "generate_image"}, studio = True)
+ tool_facts.note_mcp_tool(
+ media, {"name": "list_media", "annotations": {"readOnlyHint": True}}, studio = True
+ )
+ controller = ToolLoopController(tools = [_tool(image), _tool(media)])
+ for name, args in (
+ (image, {"prompt": "a cat"}),
+ (media, {}),
+ (image, {"prompt": "a cat"}),
+ (media, {}),
+ ):
+ decision = controller.prepare_call(_call(name, args))
+ assert decision.action == "execute", name
+ controller.record_result(decision, '{"ok":true}')
+ # Nothing new since that read: a third identical list is still a duplicate.
+ assert controller.prepare_call(_call(media, {})).action == "duplicate"
+
+
+def test_unsloths_own_generators_run_again_on_identical_arguments():
+ # No seed: each call draws one, so "two images of a cat" is two calls with the same arguments.
+ names = [f"mcp__unsloth__{n}" for n in ("generate_image", "generate_audio", "generate_video")]
+ for name in names:
+ tool_facts.note_mcp_tool(name, {"name": name.split("__")[2]}, studio = True)
+ controller = ToolLoopController(tools = [_tool(name) for name in names])
+ for name in names:
+ for _ in range(2):
+ decision = controller.prepare_call(_call(name, {"prompt": "a cat"}))
+ assert decision.action == "execute", name
+ controller.record_result(decision, '{"ok":true}')
+ # The same tool name on another server is still deduplicated.
+ tool_facts.note_mcp_tool("mcp__other__generate_image", {"name": "generate_image"})
+ other = ToolLoopController(tools = [_tool("mcp__other__generate_image")])
+ other.record_result(
+ other.prepare_call(_call("mcp__other__generate_image", {"prompt": "a cat"})), "{}"
+ )
+ assert (
+ other.prepare_call(_call("mcp__other__generate_image", {"prompt": "a cat"})).action
+ == "duplicate"
+ )
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 01c298d443d..db673a5ffcb 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -1681,6 +1681,26 @@ def test_failed_background_generate_retains_terminal_error(fake_runtime, tmp_pat
assert backend.generate_progress()["phase"] == "failed"
+def test_a_stopped_generation_ticket_cancels_the_video_job(fake_runtime, tmp_path, monkeypatch):
+ from core.inference.generation_ticket import GenerationTicket, generation_ticket
+
+ backend = VideoBackend()
+ _load_gguf(backend, tmp_path)
+ running, stopped, pipe = threading.Event(), threading.Event(), type(backend._state.pipe)
+
+ @functools.wraps(pipe.__call__) # its signature says which arguments to pass
+ def _hold(self, *_args, **_kwargs):
+ running.set()
+ if backend._active_generate_cancel.wait(10):
+ stopped.set()
+ raise ValueError("stopped")
+
+ monkeypatch.setattr(pipe, "__call__", _hold)
+ with generation_ticket(ticket := GenerationTicket()):
+ backend.begin_generate(prompt = "a clip")
+ assert running.wait(10) and ticket.stop() is True and stopped.wait(10)
+
+
def test_cache_bytes_counts_incomplete_blobs(fake_runtime, tmp_path, monkeypatch):
# scan_cache_dir skips *.incomplete blobs; count both, without double-counting symlinks.
import core.inference.video as video_mod
diff --git a/studio/backend/utils/account_context.py b/studio/backend/utils/account_context.py
index b18d5bfb1a7..4f6a8277ce7 100644
--- a/studio/backend/utils/account_context.py
+++ b/studio/backend/utils/account_context.py
@@ -8,7 +8,7 @@ from __future__ import annotations
import threading
from contextvars import ContextVar, Token
from dataclasses import dataclass, field, replace
-from typing import Any, Awaitable, Callable, TypeVar
+from typing import Any, Awaitable, Callable, Optional, TypeVar
OWNER_ACCOUNT_ID = "owner"
OWNER_USERNAME = "unsloth"
@@ -25,8 +25,16 @@ class AccountContext:
account_id: str
username: str
role: str = ROLE_USER
+ # Generation the request authenticated under, for minting a credential later; not identity.
+ credential_gen: Optional[str] = field(default = None, compare = False, repr = False)
# An sk-unsloth key or keyless API access admitted the request, not a UI session; not part of identity.
via_api_key: bool = field(default = False, compare = False)
+ # core.inference.load_policy.LoadPolicy value the credential allows; not part of identity.
+ load_policy: str = field(default = "any", compare = False)
+ # The chat tools key of a signed-in UI chat, not one an API key started; not part of identity.
+ ui_chat: bool = field(default = False, compare = False)
+ # The api_keys row that admitted the request, if any; not part of identity.
+ key_id: Optional[int] = field(default = None, compare = False)
@property
def is_owner(self) -> bool:
diff --git a/studio/backend/utils/api_errors.py b/studio/backend/utils/api_errors.py
index be0222d926b..fa1b18902dd 100644
--- a/studio/backend/utils/api_errors.py
+++ b/studio/backend/utils/api_errors.py
@@ -44,6 +44,22 @@ ANTHROPIC_TYPE_BY_STATUS = {
}
+# A machine-readable code for an agent-actionable failure, as ``code k=v ...``. A header, so the
+# body (and the detail text the frontend shows) stays exactly as it was.
+PROBLEM_HEADER = "X-Unsloth-Problem"
+_PROBLEM_TOKEN = re.compile(r"^[A-Za-z0-9_.:/-]{1,200}$")
+
+
+def problem_headers(code: str, **fields) -> dict:
+ """``{PROBLEM_HEADER: "code k=v"}``; a field that is unset or not a plain token is left out."""
+ pairs = [
+ f"{key}={value}"
+ for key, value in fields.items()
+ if value is not None and _PROBLEM_TOKEN.match(str(value))
+ ]
+ return {PROBLEM_HEADER: " ".join([code, *pairs])}
+
+
def openai_error_body(
message,
*,
diff --git a/studio/frontend/src/components/assistant-ui/link-context-menu.tsx b/studio/frontend/src/components/assistant-ui/link-context-menu.tsx
index b19aa4833d6..b38ca8e8b2d 100644
--- a/studio/frontend/src/components/assistant-ui/link-context-menu.tsx
+++ b/studio/frontend/src/components/assistant-ui/link-context-menu.tsx
@@ -118,6 +118,13 @@ export function loadSandboxFile(sessionId: string, file: string): Promise<Blob>
});
}
+export function loadBackendFile(path: string): Promise<Blob> {
+ return authFetch(path).then((response) => {
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ return response.blob();
+ });
+}
+
export function FileContextMenu({
file,
children,
diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index 9f690760f0c..9ebc9e25d3b 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -42,6 +42,7 @@ import {
import { preprocessLaTeX } from "@/lib/latex";
import { withDataImageSupport } from "@/lib/markdown-data-images";
import { downloadFile, isDownloadCancelled, urlToBlob } from "@/lib/native-files";
+import { backendPathUrl, desktopSignedMediaPath, protectedBackendPath } from "@/lib/api-base";
import { openLink } from "@/lib/open-link";
import { safeMarkdownUrl } from "@/lib/safe-markdown-url";
import { Tick02Icon } from "@/lib/tick-icon";
@@ -116,6 +117,7 @@ import { AudioPlayer } from "./audio-player";
import {
type ContextFile,
FileContextMenu,
+ loadBackendFile,
loadSandboxFile,
WebLinkContextMenu,
} from "./link-context-menu";
@@ -235,10 +237,12 @@ const MarkdownImage = memo(function MarkdownImage(props: ComponentProps<"img">)
const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
const projectId = useChatProjectScope();
const file = src
- ? markdownSandboxImageSrc(src, {
+ ? (markdownSandboxImageSrc(src, {
threadId: remoteId ?? activeThreadId ?? undefined,
projectId,
- })
+ }) ??
+ desktopSignedMediaPath(src) ??
+ protectedBackendPath(src))
: null;
const sandbox = useSandboxImage(file);
const [failedSrc, setFailedSrc] = useState<string | null>(null);
@@ -362,13 +366,22 @@ function MarkdownLink({ href, children, ...props }: ComponentProps<"a">) {
</SandboxFileLink>
);
}
+ const backend = href ? protectedBackendPath(href) : null;
+ if (backend !== null) {
+ return (
+ <BackendFileLink href={backend} dom={dom}>
+ {children}
+ </BackendFileLink>
+ );
+ }
+ const target = href ? backendPathUrl(href) : href;
const link = (
<a
- href={href}
+ href={target}
rel="noopener noreferrer"
className={LINK_CLASS}
onClick={(e) => {
- if (href && openLink(href)) {
+ if (target && openLink(target)) {
e.preventDefault();
}
}}
@@ -377,7 +390,57 @@ function MarkdownLink({ href, children, ...props }: ComponentProps<"a">) {
{children}
</a>
);
- return href ? <WebLinkContextMenu href={href}>{link}</WebLinkContextMenu> : link;
+ return target ? <WebLinkContextMenu href={target}>{link}</WebLinkContextMenu> : link;
+}
+
+/** A backend file the chat's tools linked (a saved voice sample): fetched with the session's credentials. */
+function BackendFileLink({
+ href,
+ dom,
+ children,
+}: {
+ href: string;
+ dom: Omit<ComponentProps<"a">, "href" | "children">;
+ children: ReactNode;
+}) {
+ const t = useT();
+ const parts = href.split(/[?#]/)[0].split("/").filter(Boolean);
+ const tail = decodeSegment(parts.at(-1) ?? "");
+ const base = tail === "file" ? decodeSegment(parts.at(-2) ?? "file") : tail;
+ const named = (blob: Blob) => {
+ const ext = blob.type.split("/")[1]?.split(/[;+]/)[0];
+ return base.includes(".") || !ext ? base : `${base}.${ext === "mpeg" ? "mp3" : ext}`;
+ };
+ const target: ContextFile = { name: base, load: () => loadBackendFile(href) };
+ const openFile = () => {
+ void target
+ .load()
+ .then(async (blob) => {
+ if (filesOpenInBrowser()) {
+ openFileInBrowser({ blob, name: named(blob), contentType: blob.type, key: `backend:${href}` });
+ return;
+ }
+ await downloadFile(blob, named(blob), blob.type || undefined);
+ })
+ .catch((error) => {
+ if (!isDownloadCancelled(error)) toast.error(t("linkMenu.openFailed", { name: base }));
+ });
+ };
+ return (
+ <FileContextMenu file={{ ...target, open: openFile }}>
+ <a
+ href={backendPathUrl(href)}
+ className={LINK_CLASS}
+ onClick={(event) => {
+ event.preventDefault();
+ openFile();
+ }}
+ {...dom}
+ >
+ {children}
+ </a>
+ </FileContextMenu>
+ );
}
function SandboxFileLink({
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index c5e2ffdb963..1c83b3b9174 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -43,7 +43,10 @@ import {
} from "./api/mcp-servers-api";
import { BlenderMcpSetup } from "./blender-mcp-setup";
import { ChatMcpServersDialog } from "./chat-mcp-servers-dialog";
-import { normalizeMcpUrl } from "./mcp-server-url";
+import {
+ UNSLOTH_STUDIO_TOOLS_MCP_URL,
+ normalizeMcpUrl,
+} from "./mcp-server-url";
import { useChatActive } from "./runtime-provider";
import { useChatRuntimeStore } from "./stores/chat-runtime-store";
import { useMcpServersDialogStore } from "./stores/mcp-servers-dialog-store";
@@ -57,8 +60,14 @@ type McpPreset = {
disablesWebSearch?: boolean;
};
-// Keyless remote MCP presets (rate-limited free tiers).
+// Unsloth's own tools, then keyless remote presets (rate-limited free tiers). Hugging Face
+// runs anonymously; add a token via "Manage MCP servers".
const MCP_PRESETS: readonly McpPreset[] = [
+ {
+ id: "unsloth-studio",
+ displayName: "Unsloth",
+ url: UNSLOTH_STUDIO_TOOLS_MCP_URL,
+ },
{
id: "unsloth-docs",
displayName: "Unsloth Docs",
@@ -213,6 +222,7 @@ export function McpComposerButton({
(s) =>
!s.builtin_id &&
normalizeMcpUrl(s.url) !== "studio:decisions" &&
+ normalizeMcpUrl(s.url) !== "studio:tools" &&
!presets.some((p) => normalizeMcpUrl(p.url) === normalizeMcpUrl(s.url)),
);
const blenderEnabled = servers.some(
diff --git a/studio/frontend/src/features/chat/mcp-server-url.ts b/studio/frontend/src/features/chat/mcp-server-url.ts
index 5fdf3d345c2..ddabe756a37 100644
--- a/studio/frontend/src/features/chat/mcp-server-url.ts
+++ b/studio/frontend/src/features/chat/mcp-server-url.ts
@@ -1,6 +1,8 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+export const UNSLOTH_STUDIO_TOOLS_MCP_URL = "http://127.0.0.1/mcp/studio-tools";
+
const HTTP_AUTHORITY =
/^[hH][tT][tT][pP]:\/\/(?:[^/?#]*@)?(\[[^\]]+\]|[^/:?#]+)(?::[^/?#]*)?(?=\/|[?#]|$)/;
@@ -33,7 +35,8 @@ function isStudioLoopbackHost(host: string): boolean {
}
}
-// mcp_servers has no UNIQUE(url); normalize loopback spellings so presets reuse old rows.
+// mcp_servers has no UNIQUE(url); normalize Studio's in-process Decisions and tools endpoints so a preset
+// toggle reuses rows saved under older ports and every backend-accepted loopback spelling.
export function normalizeMcpUrl(url: string): string {
const trimmed = (url || "").trim().replace(/\/+$/, "");
const comparable = trimmed.replace(/[\t\n\r]/g, "");
@@ -46,6 +49,9 @@ export function normalizeMcpUrl(url: string): string {
if (rawPath === "/mcp/decisions") {
return "studio:decisions";
}
+ if (rawPath === "/mcp/studio-tools") {
+ return "studio:tools";
+ }
}
return trimmed.toLowerCase();
}
diff --git a/studio/frontend/src/features/settings/api/mcp-access.ts b/studio/frontend/src/features/settings/api/mcp-access.ts
index 17a06c0cd4d..effd785e37d 100644
--- a/studio/frontend/src/features/settings/api/mcp-access.ts
+++ b/studio/frontend/src/features/settings/api/mcp-access.ts
@@ -11,6 +11,7 @@ export type McpToolSetting = {
/** the tool's module, used to group rows */
area: string;
enabled: boolean;
+ chat?: boolean;
};
export type McpAccessSettings = {
@@ -38,10 +39,11 @@ export function mcpAccessFromApi(
forcedByEnv: settings.forced_by_env,
url: settings.url,
tools: Array.isArray(settings.tools)
- ? settings.tools.map(({ name, area, enabled }) => ({
+ ? settings.tools.map(({ name, area, enabled, chat }) => ({
name,
area,
enabled,
+ ...(typeof chat === "boolean" ? { chat } : {}),
}))
: null,
};
diff --git a/studio/frontend/src/features/settings/components/mcp-access-section.tsx b/studio/frontend/src/features/settings/components/mcp-access-section.tsx
index 246ff88a896..511d03d50c2 100644
--- a/studio/frontend/src/features/settings/components/mcp-access-section.tsx
+++ b/studio/frontend/src/features/settings/components/mcp-access-section.tsx
@@ -14,7 +14,7 @@ import { Switch } from "@/components/ui/switch";
import { McpServerIcon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
import { usePlatformStore } from "@/config/env";
-import { translate, useT } from "@/i18n";
+import { translate, useLocale, useT } from "@/i18n";
import { isTauri } from "@/lib/api-base";
import { cn } from "@/lib/utils";
import {
@@ -44,6 +44,7 @@ import {
buildMcpSnippet,
hasMcpSnippet,
} from "./mcp-agent-snippet";
+import { mcpToolLabelKey } from "./mcp-tool-labels";
import { McpToolsDialog } from "./mcp-tools-dialog";
import { SettingsRow } from "./settings-row";
import { readUseTunnelPref, subscribeUseTunnelPref } from "./tunnel-preference";
@@ -66,6 +67,7 @@ export function McpAccessSection({
apiKey?: string | null;
}): ReactElement | null {
const t = useT();
+ const locale = useLocale();
const pillId = useId();
const [settings, setSettings] = useState<McpAccessSettings | null>(null);
const [busy, setBusy] = useState(false);
@@ -210,6 +212,25 @@ export function McpAccessSection({
buildMcpSnippet(agent, settings.url, os, apiKey))
: null;
const agentDetails = detailsFor(agent);
+ // One note for the tools a chat never gets, instead of a label on each row.
+ const chatDenied = (settings?.tools ?? [])
+ .filter((tool) => tool.chat === false)
+ .map((tool) => {
+ const key = mcpToolLabelKey(tool.name);
+ return key ? t(key) : tool.name;
+ });
+ const chatNote =
+ chatDenied.length > 0
+ ? t("settings.mcp.tools.chatNote", {
+ tools:
+ typeof Intl.ListFormat === "function"
+ ? new Intl.ListFormat(locale, {
+ style: "long",
+ type: "conjunction",
+ }).format(chatDenied)
+ : chatDenied.join(", "),
+ })
+ : null;
return (
<div
@@ -362,6 +383,7 @@ export function McpAccessSection({
tools={settings.tools}
error={toolsError}
onSave={(states) => void saveTools(states)}
+ footnote={chatNote}
/>
) : null}
</div>
diff --git a/studio/frontend/src/features/settings/components/mcp-tools-dialog.tsx b/studio/frontend/src/features/settings/components/mcp-tools-dialog.tsx
index a24200a453c..d48f8ad0056 100644
--- a/studio/frontend/src/features/settings/components/mcp-tools-dialog.tsx
+++ b/studio/frontend/src/features/settings/components/mcp-tools-dialog.tsx
@@ -233,6 +233,7 @@ export function McpToolsDialog({
tools,
error,
onSave,
+ footnote,
}: {
open: boolean;
onOpenChange: (open: boolean) => void;
@@ -240,6 +241,7 @@ export function McpToolsDialog({
error: string | null;
/** Receives the tools to change, by name; the server merges them into its list. */
onSave: (states: Record<string, boolean>) => void;
+ footnote?: string | null;
}): ReactElement {
const t = useT();
const groups = groupMcpTools(tools);
@@ -309,6 +311,11 @@ export function McpToolsDialog({
</div>
</section>
))}
+ {footnote ? (
+ <p className="px-3 text-xs leading-snug text-muted-foreground">
+ {footnote}
+ </p>
+ ) : null}
</div>
{/* A rule shows only while more of the list is below, so nothing hides behind the footer. */}
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index ec4fe513aa0..682e7d314cd 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -3430,6 +3430,7 @@ export const ar = {
jobs: "المهام",
other: "أخرى",
},
+ chatNote: "لا تحصل الدردشة أبدًا على {tools}.",
},
status: {
on: "مفعّل",
diff --git a/studio/frontend/src/i18n/locales/cs.ts b/studio/frontend/src/i18n/locales/cs.ts
index 1d67e4efcc6..55b091877f5 100644
--- a/studio/frontend/src/i18n/locales/cs.ts
+++ b/studio/frontend/src/i18n/locales/cs.ts
@@ -3916,6 +3916,7 @@ export const cs = {
description:
"Každý zapnutý nástroj přidává k tomu, co agenti čtou před začátkem, takže vypněte ty, které nepotřebujete. Agenti vypnutý nástroj nikdy nevidí a jeho volání jsou odmítnuta. Už připojení agenti uvidí změnu po opětovném připojení.",
saveError: "Nastavení nástrojů Unsloth MCP se nepodařilo uložit.",
+ chatNote: "Chat nikdy nedostane {tools}.",
groups: {
models: "Modely",
generate: "Generování",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index c6ec65d8ae5..8cd9ef01ec1 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -3476,6 +3476,7 @@ export const de = {
jobs: "Jobs",
other: "Sonstiges",
},
+ chatNote: "Der Chat bekommt nie {tools}.",
},
status: {
on: "An",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 08e3712ad54..4a6406696ce 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -3624,6 +3624,7 @@ export const en = {
jobs: "Jobs",
other: "Other",
},
+ chatNote: "The chat never gets {tools}.",
},
status: {
on: "On",
diff --git a/studio/frontend/src/i18n/locales/es-419.ts b/studio/frontend/src/i18n/locales/es-419.ts
index 4e64157dc33..3768330ab26 100644
--- a/studio/frontend/src/i18n/locales/es-419.ts
+++ b/studio/frontend/src/i18n/locales/es-419.ts
@@ -3959,6 +3959,7 @@ export const es419 = {
description:
"Cada herramienta activada se suma a lo que los agentes leen antes de empezar, así que desactiva las que no necesites. Los agentes nunca ven una herramienta desactivada y sus llamadas se rechazan. Los agentes ya conectados ven el cambio al volver a conectarse.",
saveError: "No se pudo guardar la configuración de herramientas de Unsloth MCP.",
+ chatNote: "El chat nunca recibe {tools}.",
groups: {
models: "Modelos",
generate: "Generar",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 911393f41e6..c3a09b0bcbd 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -3469,6 +3469,7 @@ export const es = {
jobs: "Trabajos",
other: "Otras",
},
+ chatNote: "El chat nunca recibe {tools}.",
},
status: {
on: "Activado",
diff --git a/studio/frontend/src/i18n/locales/fa.ts b/studio/frontend/src/i18n/locales/fa.ts
index 02ed0a322c7..a80788e395a 100644
--- a/studio/frontend/src/i18n/locales/fa.ts
+++ b/studio/frontend/src/i18n/locales/fa.ts
@@ -3885,6 +3885,7 @@ export const fa = {
description:
"هر ابزاری که روشن بماند به چیزی که عامل‌ها پیش از شروع می‌خوانند اضافه می‌شود، پس آن‌هایی را که لازم ندارید خاموش کنید. عامل‌ها هیچ‌وقت ابزار خاموش را نمی‌بینند و فراخوانی آن رد می‌شود. عامل‌هایی که از قبل وصل‌اند پس از اتصال دوباره تغییر را می‌بینند.",
saveError: "ذخیره تنظیم ابزارهای Unsloth MCP ممکن نشد.",
+ chatNote: "گفتگو هرگز {tools} را دریافت نمی‌کند.",
groups: {
models: "مدل‌ها",
generate: "تولید",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index b92fe1953e6..41be44818a1 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -3476,6 +3476,7 @@ export const fr = {
jobs: "Tâches",
other: "Autres",
},
+ chatNote: "Le chat ne reçoit jamais {tools}.",
},
status: {
on: "Activé",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index ac0e3d82dfc..50969a116b3 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -3512,6 +3512,7 @@ export const he = {
jobs: "משימות",
other: "אחר",
},
+ chatNote: "הצ'אט אף פעם לא מקבל את {tools}.",
},
status: {
on: "פועל",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index 91faa2920bf..95a99349f38 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -3439,6 +3439,7 @@ export const hi = {
jobs: "जॉब",
other: "अन्य",
},
+ chatNote: "चैट को {tools} कभी नहीं मिलते।",
},
status: {
on: "चालू",
diff --git a/studio/frontend/src/i18n/locales/id.ts b/studio/frontend/src/i18n/locales/id.ts
index 87d0ee28545..353d3927036 100644
--- a/studio/frontend/src/i18n/locales/id.ts
+++ b/studio/frontend/src/i18n/locales/id.ts
@@ -3899,6 +3899,7 @@ export const id = {
description:
"Setiap alat yang aktif menambah apa yang dibaca agen sebelum mulai, jadi nonaktifkan yang tidak Anda perlukan. Agen tidak pernah melihat alat yang nonaktif, dan panggilan ke alat itu ditolak. Agen yang sudah terhubung melihat perubahannya saat terhubung ulang.",
saveError: "Tidak dapat menyimpan pengaturan alat Unsloth MCP.",
+ chatNote: "Chat tidak pernah mendapatkan {tools}.",
groups: {
models: "Model",
generate: "Hasilkan",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 04734da4f91..c698b3852fa 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -3369,6 +3369,7 @@ export const it = {
jobs: "Processi",
other: "Altro",
},
+ chatNote: "La chat non riceve mai {tools}.",
},
status: {
on: "Attivo",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index d578586daea..0fb3de8ff45 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -3406,6 +3406,7 @@ export const ja = {
jobs: "ジョブ",
other: "その他",
},
+ chatNote: "チャットでは {tools} は使えません。",
},
status: {
on: "オン",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 8e318e43207..f57ccfa0756 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -3420,6 +3420,7 @@ export const ko = {
jobs: "작업",
other: "기타",
},
+ chatNote: "채팅에서는 {tools}을(를) 사용할 수 없습니다.",
},
status: {
on: "켜짐",
diff --git a/studio/frontend/src/i18n/locales/nl.ts b/studio/frontend/src/i18n/locales/nl.ts
index ef4ca26fa86..713116bbedb 100644
--- a/studio/frontend/src/i18n/locales/nl.ts
+++ b/studio/frontend/src/i18n/locales/nl.ts
@@ -3944,6 +3944,7 @@ export const nl = {
description:
"Elke tool die aan staat telt mee in wat agents lezen voordat ze beginnen, dus zet uit wat je niet nodig hebt. Agents zien een uitgezette tool nooit, en aanroepen ervan worden geweigerd. Al verbonden agents zien de wijziging als ze opnieuw verbinden.",
saveError: "Kon de instelling voor Unsloth MCP-tools niet opslaan.",
+ chatNote: "De chat krijgt nooit {tools}.",
groups: {
models: "Modellen",
generate: "Genereren",
diff --git a/studio/frontend/src/i18n/locales/pl.ts b/studio/frontend/src/i18n/locales/pl.ts
index 853962b92f3..d310937da1c 100644
--- a/studio/frontend/src/i18n/locales/pl.ts
+++ b/studio/frontend/src/i18n/locales/pl.ts
@@ -3945,6 +3945,7 @@ export const pl = {
description:
"Każde włączone narzędzie dokłada się do tego, co agenci czytają przed startem, więc wyłącz te, których nie potrzebujesz. Agenci nigdy nie widzą wyłączonego narzędzia, a jego wywołania są odrzucane. Już połączeni agenci zobaczą zmianę po ponownym połączeniu.",
saveError: "Nie udało się zapisać ustawienia narzędzi Unsloth MCP.",
+ chatNote: "Czat nigdy nie dostaje {tools}.",
groups: {
models: "Modele",
generate: "Generowanie",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index ee7cc2221ee..65d0c87ec05 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -3443,6 +3443,7 @@ export const ptBR = {
jobs: "Tarefas",
other: "Outras",
},
+ chatNote: "O chat nunca recebe {tools}.",
},
status: {
on: "Ativado",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 90b0bd125a5..60fd0097c2c 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -3442,6 +3442,7 @@ export const ru = {
jobs: "Задачи",
other: "Другое",
},
+ chatNote: "Чат никогда не получает {tools}.",
},
status: {
on: "Вкл.",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index 561aaf018b4..8402261cb50 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -3610,6 +3610,7 @@ export const sv = {
jobs: "Jobb",
other: "Övrigt",
},
+ chatNote: "Chatten får aldrig {tools}.",
},
status: {
on: "På",
diff --git a/studio/frontend/src/i18n/locales/th.ts b/studio/frontend/src/i18n/locales/th.ts
index b3ace69bf84..1949cd3836e 100644
--- a/studio/frontend/src/i18n/locales/th.ts
+++ b/studio/frontend/src/i18n/locales/th.ts
@@ -3734,6 +3734,7 @@ export const th = {
description:
"เครื่องมือทุกตัวที่เปิดไว้จะเพิ่มสิ่งที่เอเจนต์ต้องอ่านก่อนเริ่มงาน จึงควรปิดตัวที่ไม่ได้ใช้ เอเจนต์จะไม่เห็นเครื่องมือที่ปิดอยู่ และการเรียกใช้จะถูกปฏิเสธ เอเจนต์ที่เชื่อมต่ออยู่แล้วจะเห็นการเปลี่ยนแปลงเมื่อเชื่อมต่อใหม่",
saveError: "บันทึกการตั้งค่าเครื่องมือ Unsloth MCP ไม่สำเร็จ",
+ chatNote: "แชทจะไม่ได้รับ {tools}",
groups: {
models: "โมเดล",
generate: "สร้าง",
diff --git a/studio/frontend/src/i18n/locales/tr.ts b/studio/frontend/src/i18n/locales/tr.ts
index 8c893a69f83..625a103e627 100644
--- a/studio/frontend/src/i18n/locales/tr.ts
+++ b/studio/frontend/src/i18n/locales/tr.ts
@@ -3896,6 +3896,7 @@ export const tr = {
description:
"Açık bıraktığın her araç, ajanların başlamadan önce okuduğu şeye eklenir, bu yüzden ihtiyacın olmayanları kapat. Ajanlar kapalı bir aracı asla görmez ve ona yapılan çağrılar reddedilir. Zaten bağlı olan ajanlar değişikliği yeniden bağlandıklarında görür.",
saveError: "Unsloth MCP araç ayarı kaydedilemedi.",
+ chatNote: "Sohbet hiçbir zaman {tools} almaz.",
groups: {
models: "Modeller",
generate: "Üret",
diff --git a/studio/frontend/src/i18n/locales/uk.ts b/studio/frontend/src/i18n/locales/uk.ts
index 4673c897b37..a5d803dcd32 100644
--- a/studio/frontend/src/i18n/locales/uk.ts
+++ b/studio/frontend/src/i18n/locales/uk.ts
@@ -3930,6 +3930,7 @@ export const uk = {
description:
"Кожен увімкнений інструмент додається до того, що агенти читають перед початком, тож вимкніть непотрібні. Агенти ніколи не бачать вимкнений інструмент, а його виклики відхиляються. Уже підключені агенти побачать зміну після повторного підключення.",
saveError: "Не вдалося зберегти налаштування інструментів Unsloth MCP.",
+ chatNote: "Чат ніколи не отримує {tools}.",
groups: {
models: "Моделі",
generate: "Генерація",
diff --git a/studio/frontend/src/i18n/locales/vi.ts b/studio/frontend/src/i18n/locales/vi.ts
index d4755078965..17a873f6199 100644
--- a/studio/frontend/src/i18n/locales/vi.ts
+++ b/studio/frontend/src/i18n/locales/vi.ts
@@ -3899,6 +3899,7 @@ export const vi = {
description:
"Mỗi công cụ bạn bật sẽ thêm vào những gì agent đọc trước khi bắt đầu, vì vậy hãy tắt những công cụ bạn không cần. Agent không bao giờ thấy công cụ đã tắt và các lệnh gọi đến nó bị từ chối. Agent đã kết nối sẽ thấy thay đổi khi kết nối lại.",
saveError: "Không thể lưu cài đặt công cụ Unsloth MCP.",
+ chatNote: "Cuộc trò chuyện không bao giờ nhận được {tools}.",
groups: {
models: "Mô hình",
generate: "Tạo",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 821d678bb0b..fc69460b464 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -3376,6 +3376,7 @@ export const zhCN = {
jobs: "任务",
other: "其他",
},
+ chatNote: "聊天永远不会获得{tools}。",
},
status: {
on: "开",
diff --git a/studio/frontend/src/i18n/locales/zh-TW.ts b/studio/frontend/src/i18n/locales/zh-TW.ts
index 5f0723c9865..542d17d66b9 100644
--- a/studio/frontend/src/i18n/locales/zh-TW.ts
+++ b/studio/frontend/src/i18n/locales/zh-TW.ts
@@ -3711,6 +3711,7 @@ export const zhTW = {
description:
"每個開啟的工具都會增加代理程式開始前要讀取的內容,所以請關閉不需要的工具。代理程式永遠看不到已關閉的工具,對它的呼叫會被拒絕。已連線的代理程式在重新連線後才會看到變更。",
saveError: "無法儲存 Unsloth MCP 工具設定。",
+ chatNote: "聊天永遠不會取得 {tools}。",
groups: {
models: "模型",
generate: "生成",
diff --git a/studio/frontend/src/lib/api-base.ts b/studio/frontend/src/lib/api-base.ts
index 4155c123135..47bd5a2161a 100644
--- a/studio/frontend/src/lib/api-base.ts
+++ b/studio/frontend/src/lib/api-base.ts
@@ -61,4 +61,25 @@ export function isStudioUrl(url: string): boolean {
}
}
+// Media tools link to the backend origin-relative; Desktop's webview origin is not the backend's.
+export function backendPathUrl(url: string): string {
+ return /^\/(v1|api)\//.test(url) ? apiUrl(url) : url
+}
+
+// Signed backend media (the token is the credential): Desktop's img-src blocks the loopback backend, so fetch it.
+export function desktopSignedMediaPath(url: string): string | null {
+ return apiBase && /^\/(?:api|v1)\/[^?#]+\/file-signed\?token=[^&#]+$/.test(url) ? url : null
+}
+
+// A backend link without a signed token: a plain navigation carries no Authorization header, so it 401s.
+// Leading segments are a proxy's root_path, which the chat tools keep in the URLs they return.
+// isStudioUrl resolves as fetch does: "/\\evil/api/x" and tab or newline spellings are another host.
+export function protectedBackendPath(url: string): string | null {
+ return /^(?:\/[^/?#]+)*?\/(?:v1|api)\/[^?#]+(?:\?[^#]*)?$/.test(url) &&
+ !/\/file-signed\?/.test(url) &&
+ isStudioUrl(url)
+ ? url
+ : null
+}
+
export { isTauri }
diff --git a/studio/frontend/tests/api-base-studio-url.test.ts b/studio/frontend/tests/api-base-studio-url.test.ts
index 503cb8ca937..d72d43715dc 100644
--- a/studio/frontend/tests/api-base-studio-url.test.ts
+++ b/studio/frontend/tests/api-base-studio-url.test.ts
@@ -4,7 +4,14 @@
import assert from "node:assert/strict";
import { test } from "node:test";
-import { isStudioUrl, resetApiBase, setApiBase } from "../src/lib/api-base.ts";
+import {
+ backendPathUrl,
+ desktopSignedMediaPath,
+ isStudioUrl,
+ protectedBackendPath,
+ resetApiBase,
+ setApiBase,
+} from "../src/lib/api-base.ts";
test("only the backend's own URLs count as Studio's, so others never get the sign-in", () => {
assert.equal(isStudioUrl("/api/chat/attachments/a.png"), true);
@@ -18,3 +25,46 @@ test("only the backend's own URLs count as Studio's, so others never get the sig
assert.equal(isStudioUrl("//images.example/a.png"), false);
resetApiBase();
});
+
+test("on Desktop a backend link points at the backend and only signed media is a blob", () => {
+ const signed = "/v1/audio/a/file-signed?token=t";
+ assert.equal(backendPathUrl(signed), signed);
+ assert.equal(desktopSignedMediaPath(signed), null);
+ setApiBase(8888);
+ for (const [path, onBackend, blob, session] of [
+ [signed, true, true, false],
+ ["/api/x/file-signed?token=t", true, true, false],
+ ["/api/x/file-signed?token=t&x=1", true, false, false],
+ ["/v1/audio/voices/v1/file", true, false, true],
+ ["/api/gallery/x?archived=1", true, false, true],
+ ["/studio/v1/audio/voices/v1/file", false, false, true],
+ ["https://evil.example/api/x/file-signed?token=t", false, false, false],
+ ["https://example.com/v1/x", false, false, false],
+ ["//example.com/v1/x", false, false, false],
+ ["/chat", false, false, false],
+ ["/v1/", true, false, false],
+ ] as const) {
+ const url = onBackend ? `http://127.0.0.1:8888${path}` : path;
+ assert.equal(backendPathUrl(path), url, path);
+ assert.equal(desktopSignedMediaPath(path), blob ? path : null, path);
+ assert.equal(protectedBackendPath(path), session ? path : null, path);
+ }
+ resetApiBase();
+});
+
+test("a model-written link that resolves to another host never gets the session", () => {
+ // Browsers read "/\\" as "//" and drop tabs and newlines, so each of these is a network-path reference.
+ const offOrigin = [
+ "/\\attacker.example/api/x",
+ "/\t/attacker.example/api/x",
+ "/\n/attacker.example/v1/audio/voices/v/file",
+ ];
+ for (const apiBase of [null, 8888]) {
+ if (apiBase !== null) setApiBase(apiBase);
+ for (const path of offOrigin) {
+ assert.equal(protectedBackendPath(path), null, `${apiBase} ${JSON.stringify(path)}`);
+ }
+ assert.equal(protectedBackendPath("/v1/audio/voices/v1/file"), "/v1/audio/voices/v1/file");
+ resetApiBase();
+ }
+});
diff --git a/studio/frontend/tests/markdown-backend-link.test.ts b/studio/frontend/tests/markdown-backend-link.test.ts
new file mode 100644
index 00000000000..35cb6af91f1
--- /dev/null
+++ b/studio/frontend/tests/markdown-backend-link.test.ts
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc } from "./helpers/kit.ts";
+
+test("a link to a protected backend file opens through the session, not a bare navigation", () => {
+ // A saved-voice link from the chat's tools (/v1/audio/voices/<id>/file) 401s without the Bearer token.
+ // Each step stays inside its own function: MarkdownLink, then BackendFileLink.
+ const sessionLink =
+ /\nfunction MarkdownLink\((?:(?!\nfunction )[\s\S])*?const backend = href \? protectedBackendPath\(href\) : null;(?:(?!\nfunction )[\s\S])*?<BackendFileLink href=\{backend\}(?:(?!\nfunction )[\s\S])*?backendPathUrl\(href\)[\s\S]*?\nfunction BackendFileLink\((?:(?!\nfunction )[\s\S])*?loadBackendFile\(href\)(?:(?!\nfunction )[\s\S])*?event\.preventDefault\(\);\s*openFile\(\);/;
+ const markdown = readSrc("components/assistant-ui/markdown-text.tsx");
+ assert.match(markdown, sessionLink);
+ const menu = readSrc("components/assistant-ui/link-context-menu.tsx");
+ assert.match(menu, /loadBackendFile\(path[^}]*authFetch\(path\)/);
+});
diff --git a/studio/frontend/tests/markdown-image-recovery.test.ts b/studio/frontend/tests/markdown-image-recovery.test.ts
index d7be064d8fd..1e786bd33b4 100644
--- a/studio/frontend/tests/markdown-image-recovery.test.ts
+++ b/studio/frontend/tests/markdown-image-recovery.test.ts
@@ -8,7 +8,7 @@ import ts from "@typescript/typescript6";
import { readSrc } from "./helpers/kit.ts";
-function renderer() {
+function renderer(stubs: Record<string, unknown> = {}) {
const source = readSrc("components/assistant-ui/markdown-text.tsx");
const parsed = ts.createSourceFile(
"markdown-text.tsx",
@@ -63,6 +63,10 @@ function renderer() {
useSandboxImage: () => ({ state: { status: "idle" } }),
HugeiconsIcon: "icon",
Download01Icon: "download",
+ backendPathUrl: (url: string) => url,
+ desktopSignedMediaPath: () => null,
+ protectedBackendPath: () => null,
+ ...stubs,
};
runInNewContext(code, context);
return (props: Record<string, unknown>) => {
@@ -104,3 +108,17 @@ test("successful image load clears decode failure and forwards image events", ()
assert.equal(errors, 1);
assert.equal(loads, 1);
});
+
+test("a backend image never takes the loopback src Desktop blocks; a fetched one is a blob", () => {
+ const signed = "/api/inference/images/gallery/img-1/file-signed?token=t";
+ const loopback = (url: string) => `http://127.0.0.1:8888${url}`;
+ const render = renderer({ backendPathUrl: loopback });
+ assert.equal(render({ src: signed }).src, signed);
+ const state = { status: "loaded", url: "blob:media", blob: {} };
+ const useSandboxImage = () => ({ state });
+ // Signed media on Desktop, and an unsigned backend file that needs the session.
+ for (const fetch of ["desktopSignedMediaPath", "protectedBackendPath"]) {
+ const fetched = renderer({ useSandboxImage, [fetch]: (u: string) => u });
+ assert.equal(fetched({ src: signed }).src, "blob:media", fetch);
+ }
+});
diff --git a/studio/frontend/tests/mcp-access-api.test.ts b/studio/frontend/tests/mcp-access-api.test.ts
index faff3833dbf..45d42764953 100644
--- a/studio/frontend/tests/mcp-access-api.test.ts
+++ b/studio/frontend/tests/mcp-access-api.test.ts
@@ -75,6 +75,16 @@ test("the tool list is kept in server order, and an older backend without one ma
assert.equal(c.api.mcpAccessFromApi(BODY).tools, null);
});
+test("each tool keeps its chat flag, and an older backend without one leaves it unset", async () => {
+ const tools = [
+ { name: "list_models", area: "models", enabled: true, chat: true },
+ { name: "cancel", area: "cancel", enabled: true, chat: false },
+ { name: "voices", area: "library", enabled: true },
+ ];
+ const c = client(() => Response.json({ ...BODY, tools }));
+ assert.deepEqual((await c.api.loadMcpAccess()).tools, tools);
+});
+
test("saving tools sends only the full turned-off list", async () => {
const c = client(() =>
Response.json({
diff --git a/studio/frontend/tests/mcp-server-arguments.test.ts b/studio/frontend/tests/mcp-server-arguments.test.ts
index 859c91dd932..01e9f772bc3 100644
--- a/studio/frontend/tests/mcp-server-arguments.test.ts
+++ b/studio/frontend/tests/mcp-server-arguments.test.ts
@@ -11,7 +11,10 @@ import {
createMcpStdioSnapshot,
resolveMcpStdioUrl,
} from "../src/features/chat/mcp-server-form.ts";
-import { normalizeMcpUrl } from "../src/features/chat/mcp-server-url.ts";
+import {
+ normalizeMcpUrl,
+ UNSLOTH_STUDIO_TOOLS_MCP_URL,
+} from "../src/features/chat/mcp-server-url.ts";
import {
readAfterPendingMcpServerMutations,
readMcpServerMutationSnapshot,
@@ -858,6 +861,24 @@ test("the Decisions row stays hidden while the Decision API is off", () => {
);
});
+test("Unsloth Studio is the first preset, any loopback port, and never a custom row", () => {
+ const url = "http://127.0.0.1/mcp/studio-tools";
+ assert.equal(UNSLOTH_STUDIO_TOOLS_MCP_URL, url);
+ const urls = [
+ url,
+ "http://localhost:8889/mcp/studio-tools/",
+ "http://[::1]:8888/mcp/studio-tools",
+ url.replace("http", "https"),
+ url.replace("127.0.0.1", "example.com"),
+ `${url}/extra`,
+ ];
+ const studio = urls.map((u) => normalizeMcpUrl(u) === "studio:tools");
+ assert.deepEqual(studio, [true, true, true, false, false, false]);
+ const presetThenFilter =
+ /const MCP_PRESETS: readonly McpPreset\[\] = \[\s*\{\s*id: "unsloth-studio",\s*displayName: "Unsloth",\s*url: UNSLOTH_STUDIO_TOOLS_MCP_URL,[\s\S]*const customServers = servers\.filter\([^;]*normalizeMcpUrl\(s\.url\) !== "studio:tools"/;
+ assert.match(MCP_COMPOSER_BUTTON, presetThenFilter);
+});
+
test("an older Decision API settings response cannot replace a newer one", () => {
const refresh = MCP_COMPOSER_BUTTON.match(
/const refresh = useCallback\(([\s\S]*?)\n \},\n \[\],\n \);/,
diff --git a/studio/frontend/tests/mcp-tools-dialog.test.ts b/studio/frontend/tests/mcp-tools-dialog.test.ts
index 6c5eaa86eb2..8c160062ff2 100644
--- a/studio/frontend/tests/mcp-tools-dialog.test.ts
+++ b/studio/frontend/tests/mcp-tools-dialog.test.ts
@@ -185,6 +185,16 @@ test("the API tab row matches the keyless link beside it, shows the status as te
assert.equal(en.settings.mcp.apiKeysRow.open, "Open in Agents");
});
+test("tools a chat never gets are named once, in a note under the groups", () => {
+ assert.match(
+ SECTION,
+ /\.filter\(\(tool\) => tool\.chat === false\)[\s\S]*?t\("settings\.mcp\.tools\.chatNote", \{/,
+ );
+ assert.match(SECTION, /footnote=\{chatNote\}/);
+ assert.match(TOOLS, /\{footnote \? \(\s*<p /);
+ assert.doesNotMatch(TOOLS, /notInChat/);
+});
+
test("every catalog tool has a label and a description, and an unknown one falls back to its name", () => {
for (const [keys, keyOf] of [
[MCP_TOOL_LABEL_KEYS, mcpToolLabelKey],