Studio: add durable Deep Research workflows

studio/backend/core/inference/tools.py

@@ -3189,6 +3189,7 @@ def execute_tool(
     rag_scope: dict | None = None,
     disable_sandbox: bool = False,
     output_callback = None,
+    website_policy: dict | None = None,
 ) -> str:
     """Execute a tool by name with the given arguments; returns a string.
 
@@ -3205,8 +3206,20 @@ def execute_tool(
     stdout/stderr chunks while python/terminal executions run (UI live
     output). Purely observational: the returned result string is identical
     with or without it. Tools without incremental output ignore it.
+    ``website_policy``: hidden server-validated domain limits for web_search.
     """
     logger.info(f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}")
+    # Deep Research originally called this positionally before thread_id and
+    # output_callback were added upstream. Recognize that exact argument shape.
+    if (
+        website_policy is None
+        and isinstance(disable_sandbox, dict)
+        and rag_scope is False
+        and thread_id is None
+    ):
+        website_policy = disable_sandbox
+        disable_sandbox = False
+        rag_scope = None
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
     if name == "search_knowledge_base":
         return _search_knowledge_base(arguments, rag_scope)
@@ -3266,6 +3279,7 @@ def execute_tool(
             url = arguments.get("url"),
             timeout = effective_timeout,
             cancel_event = cancel_event,
+            website_policy = website_policy,
         )
     if name == "python":
         return _python_exec(
@@ -4018,6 +4032,7 @@ def _fetch_url_raw(
     extra_headers: dict | None = None,
     deadline: float | None = None,
     cancel_event = None,
+    website_policy: dict | None = None,
 ) -> tuple[str | None, str, str]:
     """Fetch a URL with SSRF protection; return ``(error, body_text, content_type)``.
 
@@ -4030,16 +4045,16 @@ def _fetch_url_raw(
     the caller goes away; both default off so callers keep the old behavior.
     """
     from urllib.parse import urlparse
+    from .web_access_policy import check_url_access
 
     parsed = urlparse(url)
-    if parsed.scheme not in ("http", "https"):
-        return f"Blocked: only http/https URLs are allowed (got {parsed.scheme!r}).", "", ""
-    if not parsed.hostname:
-        return "Blocked: URL is missing a hostname.", "", ""
+    allowed, reason, canonical_host = check_url_access(url, website_policy)
+    if not allowed:
+        return reason, "", ""
 
     port = parsed.port or (443 if parsed.scheme == "https" else 80)
     ok, reason, pinned_ip = _resolve_with_budget(
-        parsed.hostname,
+        canonical_host,
         port,
         deadline,
         cancel_event,
@@ -4053,7 +4068,7 @@ def _fetch_url_raw(
 
         max_bytes = _MAX_FETCH_BYTES
         current_url = url
-        current_host = parsed.hostname
+        current_host = canonical_host
         ua = random.choice(_USER_AGENTS)
 
         for _hop in range(5):
@@ -4067,6 +4082,10 @@ def _fetch_url_raw(
             ip_str = f"[{pinned_ip}]" if ":" in pinned_ip else pinned_ip
             ip_netloc = f"{ip_str}:{cp.port}" if cp.port else ip_str
             pinned_url = urlunparse(cp._replace(netloc = ip_netloc))
+            host_header = f"[{current_host}]" if ":" in current_host else current_host
+            default_port = 443 if cp.scheme == "https" else 80
+            if cp.port and cp.port != default_port:
+                host_header = f"{host_header}:{cp.port}"
 
             opener = urllib.request.build_opener(
                 _NoRedirect,
@@ -4075,7 +4094,7 @@ def _fetch_url_raw(
 
             headers = {
                 "User-Agent": ua,
-                "Host": current_host,
+                "Host": host_header,
             }
             if extra_headers:
                 headers.update(extra_headers)
@@ -4092,18 +4111,21 @@ def _fetch_url_raw(
                     return "Failed to fetch URL: redirect missing Location header.", "", ""
                 current_url = urljoin(current_url, location)
                 rp = urlparse(current_url)
-                if rp.scheme not in ("http", "https") or not rp.hostname:
-                    return "Blocked: redirect target is not a valid http/https URL.", "", ""
+                allowed, policy_reason, redirect_host = check_url_access(
+                    current_url, website_policy,
+                )
+                if not allowed:
+                    return policy_reason, "", ""
                 rp_port = rp.port or (443 if rp.scheme == "https" else 80)
                 ok2, reason2, pinned_ip = _resolve_with_budget(
-                    rp.hostname,
+                    redirect_host,
                     rp_port,
                     deadline,
                     cancel_event,
                 )
                 if not ok2:
                     return reason2, "", ""
-                current_host = rp.hostname
+                current_host = redirect_host
                 continue
 
             # get_content_type() defaults to "text/plain" when the header is
@@ -4294,6 +4316,7 @@ def _fetch_page_text(
     max_chars: int = _MAX_PAGE_CHARS,
     timeout: int = 30,
     cancel_event = None,
+    website_policy: dict | None = None,
 ) -> str:
     """Fetch a URL and return readable text content.
 
@@ -4308,6 +4331,12 @@ def _fetch_page_text(
     # HTML fallback both draw from it, so a slow/failed API call cannot hand the
     # fallback a fresh full timeout and double the worst case.
     deadline = None if timeout is None else time.monotonic() + timeout
+    from .web_access_policy import check_url_access
+
+    allowed, reason, _hostname = check_url_access(url, website_policy)
+    if not allowed:
+        return reason
+    policy_kwargs = {"website_policy": website_policy} if website_policy is not None else {}
     readme_api_url = _github_repo_readme_api_url(url)
     if readme_api_url:
         err, body, _ctype = _fetch_url_raw(
@@ -4319,6 +4348,7 @@ def _fetch_page_text(
             },
             deadline = deadline,
             cancel_event = cancel_event,
+            **policy_kwargs,
         )
         # The README API is unauthenticated and rate-limited; on any failure fall
         # back to the HTML page fetch. A 200 body is authoritative even when it is
@@ -4344,6 +4374,7 @@ def _fetch_page_text(
         timeout = timeout,
         deadline = deadline,
         cancel_event = cancel_event,
+        **policy_kwargs,
     )
     if err is not None:
         return err
@@ -4369,6 +4400,7 @@ def _web_search(
     timeout: int = _EXEC_TIMEOUT,
     url: str | None = None,
     cancel_event = None,
+    website_policy: dict | None = None,
 ) -> str:
     """Search the web using DuckDuckGo and return formatted results.
 
@@ -4381,6 +4413,7 @@ def _web_search(
             url.strip(),
             timeout = fetch_timeout,
             cancel_event = cancel_event,
+            website_policy = website_policy,
         )
 
     if not query or not query.strip():
@@ -4393,18 +4426,29 @@ def _web_search(
     try:
         from ddgs import DDGS
 
-        results = DDGS(timeout = timeout).text(query, max_results = max_results)
+        from .web_access_policy import check_url_access, scope_search_query
+
+        effective_query = scope_search_query(query, website_policy)
+        results = DDGS(timeout = timeout).text(effective_query, max_results = max_results)
         if cancel_event is not None and cancel_event.is_set():
             return "Search cancelled."
         if not results:
             return "No results found."
         parts = []
         for r in results:
+            href = str(r.get("href") or "").strip()
+            allowed, _reason, _hostname = check_url_access(href, website_policy)
+            if not allowed:
+                continue
+            title = " ".join(str(r.get("title") or "").split())
+            snippet = " ".join(str(r.get("body") or "").split())
             parts.append(
-                f"Title: {r.get('title', '')}\n"
-                f"URL: {r.get('href', '')}\n"
-                f"Snippet: {r.get('body', '')}"
+                f"Title: {title}\n"
+                f"URL: {href}\n"
+                f"Snippet: {snippet}"
             )
+        if not parts:
+            return "No results found within the website access limits."
         text = "\n\n---\n\n".join(parts)
         text += (
             "\n\n---\n\nIMPORTANT: These are only short snippets. "

studio/backend/core/inference/web_access_policy.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
+
+"""Canonical website access policies for server-side web tools."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+_DOMAIN_LABEL = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_MAX_DOMAINS_PER_LIST = 100
+
+
+def normalize_domain(value: Any) -> str:
+    domain = str(value or "").strip().lower()
+    if not domain:
+        raise ValueError("Website domains cannot be empty")
+    if any(ord(char) < 32 for char in domain) or any(
+        char in domain for char in ("\\", "/", "@", "?", "#")
+    ):
+        raise ValueError(f"Invalid website domain: {value!r}")
+    bracketed = domain.startswith("[") and domain.endswith("]")
+    if domain.startswith("[") != domain.endswith("]"):
+        raise ValueError(f"Invalid website domain: {value!r}")
+    domain = (domain[1:-1] if bracketed else domain).rstrip(".")
+    try:
+        return ipaddress.ip_address(domain).compressed
+    except ValueError:
+        pass
+    if ":" in domain:
+        raise ValueError("Website limits must contain domains without schemes or ports")
+    numeric_parts = domain.split(".")
+    if len(numeric_parts) <= 4 and all(
+        re.fullmatch(r"(?:0x[0-9a-f]+|[0-9]+)", part) for part in numeric_parts
+    ):
+        raise ValueError("Non-canonical numeric IP hostnames are not allowed")
+    try:
+        ascii_domain = domain.encode("idna").decode("ascii").lower()
+    except UnicodeError as exc:
+        raise ValueError(f"Invalid website domain: {value!r}") from exc
+    if len(ascii_domain) > 253 or not all(
+        _DOMAIN_LABEL.fullmatch(label) for label in ascii_domain.split(".")
+    ):
+        raise ValueError(f"Invalid website domain: {value!r}")
+    return ascii_domain
+
+
+def normalize_website_policy(value: Any) -> dict[str, list[str]]:
+    if value is None:
+        return {"allowedDomains": [], "blockedDomains": []}
+    if not isinstance(value, dict):
+        raise ValueError("websitePolicy must be an object")
+    unknown = set(value) - {"allowedDomains", "blockedDomains"}
+    if unknown:
+        raise ValueError(f"Unsupported websitePolicy fields: {', '.join(sorted(unknown))}")
+
+    normalized: dict[str, list[str]] = {}
+    for key in ("allowedDomains", "blockedDomains"):
+        raw_domains = value.get(key, [])
+        if not isinstance(raw_domains, list):
+            raise ValueError(f"{key} must be a list")
+        if len(raw_domains) > _MAX_DOMAINS_PER_LIST:
+            raise ValueError(f"{key} supports at most {_MAX_DOMAINS_PER_LIST} domains")
+        domains: list[str] = []
+        for raw_domain in raw_domains:
+            domain = normalize_domain(raw_domain)
+            if domain not in domains:
+                domains.append(domain)
+        normalized[key] = domains
+    return normalized
+
+
+def _matches_domain(hostname: str, domain: str) -> bool:
+    return hostname == domain or hostname.endswith(f".{domain}")
+
+
+def hostname_allowed(hostname: str, policy: dict[str, Any] | None) -> bool:
+    try:
+        host = normalize_domain(hostname)
+        normalized = normalize_website_policy(policy)
+    except ValueError:
+        return False
+    blocked = normalized["blockedDomains"]
+    if any(_matches_domain(host, domain) for domain in blocked):
+        return False
+    allowed = normalized["allowedDomains"]
+    return not allowed or any(_matches_domain(host, domain) for domain in allowed)
+
+
+def check_url_access(
+    url: str, policy: dict[str, Any] | None,
+) -> tuple[bool, str, str]:
+    """Return ``(allowed, reason, canonical_hostname)`` for an HTTP(S) URL."""
+    if not isinstance(url, str) or not url.strip():
+        return False, "Blocked: URL is empty.", ""
+    candidate = url.strip()
+    if any(char.isspace() or ord(char) < 32 for char in candidate) or "\\" in candidate:
+        return False, "Blocked: URL contains invalid characters.", ""
+    try:
+        parsed = urlsplit(candidate)
+        if parsed.scheme.lower() not in ("http", "https"):
+            return False, "Blocked: only http/https URLs are allowed.", ""
+        if parsed.username is not None or parsed.password is not None or "%" in parsed.netloc:
+            return False, "Blocked: URL credentials or encoded hostnames are not allowed.", ""
+        hostname = normalize_domain(parsed.hostname)
+        _ = parsed.port
+    except (TypeError, ValueError):
+        return False, "Blocked: URL has an invalid hostname or port.", ""
+    if not hostname_allowed(hostname, policy):
+        return False, f"Blocked by website access policy: {hostname}.", hostname
+    return True, "", hostname
+
+
+def website_policy_prompt(policy: dict[str, Any] | None) -> str:
+    normalized = normalize_website_policy(policy)
+    allowed = normalized["allowedDomains"]
+    blocked = normalized["blockedDomains"]
+    if not allowed and not blocked:
+        return ""
+    lines = ["Website access limits are enforced by the application."]
+    if allowed:
+        lines.append(
+            "Only search or fetch these domains and their subdomains: "
+            + ", ".join(allowed)
+            + ". Do not propose, cite, or attempt any other website."
+        )
+    if blocked:
+        lines.append(
+            "Never search or fetch these domains or their subdomains: "
+            + ", ".join(blocked)
+            + "."
+        )
+    lines.append(
+        "Blocked search results are unavailable; do not try to work around these limits."
+    )
+    return "\n".join(lines)
+
+
+def scope_search_query(query: str, policy: dict[str, Any] | None) -> str:
+    allowed = normalize_website_policy(policy)["allowedDomains"]
+    if not allowed or len(allowed) > 8:
+        return query
+    site_filter = " OR ".join(f"site:{domain}" for domain in allowed)
+    return f"{query} ({site_filter})"

studio/backend/main.py

@@ -304,6 +304,7 @@ from routes import (
     models_router,
     providers_router,
     rag_router,
+    research_runs_router,
     training_history_router,
     training_router,
 )
@@ -546,6 +547,10 @@ async def lifespan(app: FastAPI):
     _start_helper_precache_if_enabled()
     threading.Thread(target = _warm_rag_embedder, daemon = True, name = "rag-embedder-warm").start()
 
+    from core.research_runs import ResearchSupervisor
+    app.state.research_supervisor = ResearchSupervisor(app)
+    app.state.research_supervisor.start()
+
     # Idle auto-unload loop (no-op unless the OpenAI auto-unload TTL is set).
     from core.inference.llama_keepwarm import idle_unload_loop
 
@@ -594,6 +599,10 @@ async def lifespan(app: FastAPI):
         except asyncio.CancelledError:
             pass
 
+    _research_supervisor = getattr(app.state, "research_supervisor", None)
+    if _research_supervisor is not None:
+        await _research_supervisor.stop()
+
     from core.inference.llama_http import aclose as _close_llama_http
 
     await _close_llama_http()
@@ -955,6 +964,9 @@ app.include_router(auth_router, prefix = "/api/auth", tags = ["auth"])
 app.include_router(training_router, prefix = "/api/train", tags = ["training"])
 app.include_router(models_router, prefix = "/api/models", tags = ["models"])
 app.include_router(chat_history_router, prefix = "/api/chat", tags = ["chat"])
+app.include_router(
+    research_runs_router, prefix = "/api/chat/research-runs", tags = ["research-runs"]
+)
 app.include_router(inference_router, prefix = "/api/inference", tags = ["inference"])
 # Studio-only inference endpoints (cancel, etc.) are NOT exposed on the /v1
 # OpenAI-compat prefix below.

studio/backend/routes/__init__.py

@@ -18,6 +18,7 @@ from routes.chat_history import router as chat_history_router
 from routes.providers import router as providers_router
 from routes.mcp_servers import router as mcp_servers_router
 from routes.rag import router as rag_router
+from routes.research_runs import router as research_runs_router
 
 __all__ = [
     "training_router",
@@ -33,7 +34,8 @@ __all__ = [
     "providers_router",
     "mcp_servers_router",
     "rag_router",
+    "research_runs_router",
 ]
 
 # Bind the re-export so the import-hoist verifier counts it as used.
-_ = (rag_router,)
+_ = (rag_router, research_runs_router)

studio/backend/routes/research_runs.py

@@ -0,0 +1,341 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Authenticated durable inline Deep Research API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+from auth.authentication import get_current_subject
+from core.inference.web_access_policy import normalize_website_policy
+from storage import research_runs_db as db
+from storage.studio_db import get_chat_message, get_chat_thread, upsert_chat_message
+
+router = APIRouter()
+_SENSITIVE_KEY = re.compile(r"^(?:api.?key|secret|token|authorization|password)$", re.IGNORECASE)
+_MAX_PLAN_STEPS = 30
+
+
+class CreateResearchRun(BaseModel):
+    model_config = ConfigDict(extra = "forbid")
+    threadId: str
+    userMessageId: str
+    assistantMessageId: str | None = Field(
+        default = None,
+        validation_alias = AliasChoices("unstable_assistantMessageId", "assistantMessageId"),
+    )
+    inferenceRequest: dict[str, Any] = Field(default_factory = dict)
+    ragScope: dict[str, Any] | None = None
+    budgets: dict[str, int] | None = None
+    websitePolicy: dict[str, list[str]] | None = None
+
+
+class ResearchPlanStep(BaseModel):
+    model_config = ConfigDict(extra = "forbid")
+    title: str = Field(min_length = 1, max_length = 200)
+    query: str = Field(min_length = 1, max_length = 500)
+
+
+class ResearchPlan(BaseModel):
+    model_config = ConfigDict(extra = "forbid")
+    title: str = Field(min_length = 1, max_length = 200)
+    steps: list[ResearchPlanStep] = Field(min_length = 1, max_length = _MAX_PLAN_STEPS)
+
+
+class UpdatePlan(BaseModel):
+    model_config = ConfigDict(extra = "forbid")
+    plan: ResearchPlan
+    expectedRevision: int = Field(ge = 0)
+
+
+class ApprovePlan(BaseModel):
+    model_config = ConfigDict(extra = "forbid")
+    planRevision: int = Field(ge = 1)
+    planHash: str = Field(min_length = 64, max_length = 64)
+
+
+def _require_run(run_id: str, subject: str) -> dict:
+    run = db.get_run(run_id, subject)
+    if run is None:
+        raise HTTPException(status_code = 404, detail = "Research run not found")
+    return run
+
+
+def _sync_assistant(run: dict, text: str | None = None) -> None:
+    message_id = db.discover_and_bind_assistant_message(run["id"])
+    if not message_id:
+        if run["status"] not in db.TERMINAL_STATUSES:
+            return
+        fallback_text = text or {
+            "cancelled": "Research cancelled.",
+            "failed": f"Research failed: {run.get('error') or 'Unknown error'}",
+            "completed": "Research completed.",
+        }[run["status"]]
+        message_id, created = db.create_and_bind_terminal_fallback(
+            run["id"], text = fallback_text, status = run["status"],
+        )
+        if created:
+            return
+    message = get_chat_message(run["threadId"], message_id)
+    if message is None:
+        return
+    content = message.get("content") if isinstance(message.get("content"), list) else []
+    if text is not None:
+        content = [part for part in content if not (
+            isinstance(part, dict) and part.get("researchRunId") == run["id"]
+        )]
+        content.append({"type": "text", "text": text, "researchRunId": run["id"]})
+    metadata = dict(message.get("metadata") or {})
+    metadata.update({
+        "researchRunId": run["id"], "researchStatus": run["status"],
+        "researchPlanRevision": run["planRevision"], "serverManaged": True,
+    })
+    upsert_chat_message({
+        **message, "content": content, "metadata": metadata,
+    })
+
+
+def _sanitize_config(payload: CreateResearchRun, thread: dict) -> dict:
+    request = dict(payload.inferenceRequest)
+    forbidden = [key for key in request if _SENSITIVE_KEY.search(str(key))]
+    if forbidden:
+        raise HTTPException(status_code = 400, detail = "Inference credentials cannot be persisted")
+    if any(key in request for key in ("baseUrl", "endpoint", "provider", "tools", "enabledTools")):
+        raise HTTPException(
+            status_code = 400,
+            detail = "Durable research currently supports only the selected local Studio model",
+        )
+    allowed = {
+        "model", "temperature", "topP", "maxTokens", "enableThinking", "reasoningEffort",
+    }
+    unknown = set(request) - allowed
+    if unknown:
+        raise HTTPException(
+            status_code = 400, detail = f"Unsupported inferenceRequest fields: {', '.join(sorted(unknown))}"
+        )
+    model = str(request.get("model") or thread.get("modelId") or "").strip()
+    if not model:
+        raise HTTPException(status_code = 400, detail = "A selected local model is required")
+    request["model"] = model
+    try:
+        if "temperature" in request:
+            request["temperature"] = float(request["temperature"])
+            if not 0 <= request["temperature"] <= 2:
+                raise ValueError
+        if "topP" in request:
+            request["topP"] = float(request["topP"])
+            if not 0 < request["topP"] <= 1:
+                raise ValueError
+        if "maxTokens" in request:
+            request["maxTokens"] = int(request["maxTokens"])
+            if not 1 <= request["maxTokens"] <= 8192:
+                raise ValueError
+        if "enableThinking" in request and not isinstance(request["enableThinking"], bool):
+            raise ValueError
+        if "reasoningEffort" in request:
+            request["reasoningEffort"] = str(request["reasoningEffort"])
+            if request["reasoningEffort"] not in {
+                "none", "minimal", "low", "medium", "high", "max", "xhigh",
+            }:
+                raise ValueError
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(status_code = 400, detail = "Invalid inferenceRequest value") from exc
+    rag_scope = payload.ragScope
+    if rag_scope is not None:
+        allowed_rag = {
+            "kb_id", "thread_id", "project_id", "default_top_k", "mode",
+            "autoinject", "autoinject_min_score", "whole_doc",
+        }
+        unknown_rag = set(rag_scope) - allowed_rag
+        if unknown_rag or any(_SENSITIVE_KEY.search(str(key)) for key in rag_scope):
+            raise HTTPException(status_code = 400, detail = "Unsupported or sensitive ragScope field")
+    budgets = {
+        "maxSteps": 12, "maxSources": 40, "modelTimeoutSeconds": 900,
+        "toolTimeoutSeconds": 120,
+    }
+    for key, value in (payload.budgets or {}).items():
+        if key not in budgets:
+            raise HTTPException(status_code = 400, detail = f"Unsupported budget: {key}")
+        budgets[key] = int(value)
+    limits = {
+        "maxSteps": (1, _MAX_PLAN_STEPS), "maxSources": (1, 100),
+        "modelTimeoutSeconds": (10, 3600), "toolTimeoutSeconds": (5, 600),
+    }
+    for key, (minimum, maximum) in limits.items():
+        if not minimum <= budgets[key] <= maximum:
+            raise HTTPException(
+                status_code = 400, detail = f"{key} must be between {minimum} and {maximum}"
+            )
+    try:
+        website_policy = normalize_website_policy(payload.websitePolicy)
+    except ValueError as exc:
+        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+    return {"model": model, "inferenceRequest": request, "ragScope": rag_scope,
+            "budgets": budgets, "websitePolicy": website_policy}
+
+
+@router.post("", status_code = 202)
+async def create_research_run(
+    payload: CreateResearchRun, request: Request,
+    current_subject: str = Depends(get_current_subject),
+):
+    thread = get_chat_thread(payload.threadId)
+    if thread is None:
+        raise HTTPException(status_code = 404, detail = "Thread not found")
+    user_message = get_chat_message(payload.threadId, payload.userMessageId)
+    if user_message is None or user_message.get("role") != "user":
+        raise HTTPException(status_code = 400, detail = "userMessageId must identify a user message in the thread")
+    if db.has_thread_claim(current_subject, payload.threadId):
+        raise HTTPException(
+            status_code = 409,
+            detail = "This thread already has a Deep Research run",
+        )
+    config = _sanitize_config(payload, thread)
+    run_id = uuid.uuid4().hex
+    assistant_id = payload.assistantMessageId
+    try:
+        run = db.create_run(
+            run_id = run_id, owner_subject = current_subject, thread_id = payload.threadId,
+            user_message_id = payload.userMessageId, assistant_message_id = assistant_id,
+            config = config,
+        )
+    except db.ResearchConflictError as exc:
+        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+    supervisor = getattr(request.app.state, "research_supervisor", None)
+    if supervisor is not None:
+        supervisor.note_request_port(request)
+        supervisor.wake()
+    return run
+
+
+@router.get("/active")
+async def active_research_runs(
+    thread_id: str = Query(alias = "threadId"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return {
+        "runs": db.list_active(current_subject, thread_id),
+        "hasRun": db.has_thread_claim(current_subject, thread_id),
+    }
+
+
+@router.get("/{run_id}")
+async def get_research_run(run_id: str, current_subject: str = Depends(get_current_subject)):
+    return _require_run(run_id, current_subject)
+
+
+@router.put("/{run_id}/plan")
+async def update_research_plan(
+    run_id: str, payload: UpdatePlan, current_subject: str = Depends(get_current_subject),
+):
+    _require_run(run_id, current_subject)
+    try:
+        db.set_plan(run_id, payload.plan.model_dump(), payload.expectedRevision)
+    except (db.ResearchConflictError, KeyError) as exc:
+        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+    run = _require_run(run_id, current_subject)
+    _sync_assistant(run)
+    return run
+
+
+@router.post("/{run_id}/approve")
+async def approve_research_plan(
+    run_id: str, payload: ApprovePlan, request: Request,
+    current_subject: str = Depends(get_current_subject),
+):
+    _require_run(run_id, current_subject)
+    try:
+        db.approve(run_id, payload.planRevision, payload.planHash)
+    except (db.ResearchConflictError, KeyError) as exc:
+        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+    supervisor = getattr(request.app.state, "research_supervisor", None)
+    if supervisor is not None:
+        supervisor.note_request_port(request)
+        supervisor.wake()
+    run = _require_run(run_id, current_subject)
+    _sync_assistant(run)
+    return run
+
+
+@router.post("/{run_id}/cancel")
+async def cancel_research_run(
+    run_id: str, request: Request,
+    current_subject: str = Depends(get_current_subject),
+):
+    _require_run(run_id, current_subject)
+    status = db.request_cancel(run_id)
+    supervisor = getattr(request.app.state, "research_supervisor", None)
+    if supervisor is not None and status == "cancelling":
+        supervisor.cancel(run_id)
+    run = _require_run(run_id, current_subject)
+    _sync_assistant(run)
+    return run
+
+
+@router.post("/{run_id}/retry")
+async def retry_research_run(
+    run_id: str, request: Request, current_subject: str = Depends(get_current_subject),
+):
+    _require_run(run_id, current_subject)
+    try:
+        db.retry(run_id)
+    except (db.ResearchConflictError, KeyError) as exc:
+        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+    supervisor = getattr(request.app.state, "research_supervisor", None)
+    if supervisor is not None:
+        supervisor.note_request_port(request)
+        supervisor.wake()
+    run = _require_run(run_id, current_subject)
+    _sync_assistant(run)
+    return run
+
+
+@router.get("/{run_id}/events")
+async def research_events(
+    run_id: str, request: Request, after: int | None = Query(None, ge = 0),
+    last_event_id: str | None = Header(None, alias = "Last-Event-ID"),
+    current_subject: str = Depends(get_current_subject),
+):
+    _require_run(run_id, current_subject)
+    header_after = int(last_event_id) if last_event_id and last_event_id.isdigit() else 0
+    cursor = max(after or 0, header_after)
+
+    async def stream():
+        nonlocal cursor
+        while True:
+            events = await asyncio.to_thread(
+                db.wait_for_events, run_id, current_subject, cursor, 15,
+            )
+            snapshot = await asyncio.to_thread(db.get_run, run_id, current_subject)
+            if snapshot is None:
+                return
+            for event in events:
+                cursor = int(event["seq"])
+                event_data = dict(event["data"])
+                event_data["createdAt"] = event["createdAt"]
+                event_data["run"] = snapshot
+                data = json.dumps(event_data, separators = (",", ":"), ensure_ascii = False)
+                yield f"id: {cursor}\nevent: {event['type']}\ndata: {data}\n\n"
+            if (
+                snapshot["status"] in db.TERMINAL_STATUSES
+                and cursor >= int(snapshot["lastEventSeq"])
+            ):
+                return
+            if await request.is_disconnected():
+                return
+            if not events:
+                yield ": keep-alive\n\n"
+
+    return StreamingResponse(
+        stream(), media_type = "text/event-stream",
+        headers = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

studio/backend/storage/research_runs_db.py

@@ -0,0 +1,943 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Transactional durable state for inline Deep Research runs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import threading
+import time
+from typing import Any
+
+from core.inference.web_access_policy import check_url_access
+from storage.studio_db import get_connection
+
+ACTIVE_STATUSES = frozenset(
+    {"planning", "awaiting_approval", "queued", "running", "paused", "cancelling"}
+)
+TERMINAL_STATUSES = frozenset({"cancelled", "completed", "failed"})
+ALL_STATUSES = ACTIVE_STATUSES | TERMINAL_STATUSES
+_EVENTS_CHANGED = threading.Condition()
+
+
+class ResearchConflictError(RuntimeError):
+    pass
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def canonical_plan(plan: dict[str, Any]) -> tuple[str, str]:
+    raw = json.dumps(plan, sort_keys = True, separators = (",", ":"), ensure_ascii = False)
+    return raw, hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _loads(value: str | None, fallback: Any) -> Any:
+    if value is None:
+        return fallback
+    try:
+        return json.loads(value)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def _event_locked(conn: sqlite3.Connection, run_id: str, event_type: str, data: dict) -> int:
+    row = conn.execute(
+        "SELECT next_event_seq, retry_count FROM research_runs WHERE id = ?", (run_id,)
+    ).fetchone()
+    if row is None:
+        raise KeyError(run_id)
+    seq = int(row["next_event_seq"])
+    created = now_ms()
+    event_data = dict(data)
+    event_data.setdefault("attempt", int(row["retry_count"]))
+    conn.execute(
+        "INSERT INTO research_events (run_id, seq, event_type, data_json, created_at) "
+        "VALUES (?, ?, ?, ?, ?)",
+        (run_id, seq, event_type, json.dumps(event_data, ensure_ascii = False), created),
+    )
+    conn.execute(
+        "UPDATE research_runs SET next_event_seq = ?, updated_at = ? WHERE id = ?",
+        (seq + 1, created, run_id),
+    )
+    return seq
+
+
+def _commit_event(conn: sqlite3.Connection) -> None:
+    conn.commit()
+    with _EVENTS_CHANGED:
+        _EVENTS_CHANGED.notify_all()
+
+
+def _worker_can_write_locked(
+    conn: sqlite3.Connection, run_id: str, worker_id: str, statuses: set[str],
+) -> bool:
+    row = conn.execute(
+        "SELECT status, lease_owner, lease_expires_at, cancel_requested "
+        "FROM research_runs WHERE id = ?", (run_id,),
+    ).fetchone()
+    return bool(
+        row is not None
+        and row["lease_owner"] == worker_id
+        and row["status"] in statuses
+        and not bool(row["cancel_requested"])
+        and row["lease_expires_at"] is not None
+        and int(row["lease_expires_at"]) >= now_ms()
+    )
+
+
+def append_event(run_id: str, event_type: str, data: dict[str, Any]) -> int:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        seq = _event_locked(conn, run_id, event_type, data)
+        _commit_event(conn)
+        return seq
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def append_worker_event(
+    run_id: str, worker_id: str, event_type: str, data: dict[str, Any],
+) -> int | None:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        if not _worker_can_write_locked(
+            conn, run_id, worker_id, {"planning", "running"},
+        ):
+            conn.commit()
+            return None
+        seq = _event_locked(conn, run_id, event_type, data)
+        _commit_event(conn)
+        return seq
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def create_run(
+    *, run_id: str, owner_subject: str, thread_id: str, user_message_id: str,
+    assistant_message_id: str | None, config: dict[str, Any], created_at: int | None = None,
+) -> dict:
+    created = created_at or now_ms()
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            conn.execute(
+                "INSERT INTO research_thread_claims (owner_subject, thread_id, created_at) "
+                "VALUES (?, ?, ?)",
+                (owner_subject, thread_id, created),
+            )
+        except sqlite3.IntegrityError as exc:
+            claim = conn.execute(
+                "SELECT 1 FROM research_thread_claims "
+                "WHERE owner_subject=? AND thread_id=?",
+                (owner_subject, thread_id),
+            ).fetchone()
+            if claim is not None:
+                raise ResearchConflictError(
+                    "This thread already has a Deep Research run"
+                ) from exc
+            raise
+        if assistant_message_id:
+            message = conn.execute(
+                "SELECT * FROM chat_messages WHERE id=?", (assistant_message_id,)
+            ).fetchone()
+            metadata = {
+                "researchRunId": run_id, "researchStatus": "planning",
+                "researchPlanRevision": 0, "serverManaged": True,
+            }
+            if message is None:
+                conn.execute(
+                    """INSERT INTO chat_messages
+                       (id, thread_id, parent_id, role, content_json, metadata_json, created_at)
+                       VALUES (?, ?, ?, 'assistant', '[]', ?, ?)""",
+                    (assistant_message_id, thread_id, user_message_id,
+                     json.dumps(metadata, ensure_ascii = False), created),
+                )
+                conn.execute(
+                    "UPDATE chat_threads SET updated_at=MAX(COALESCE(updated_at, created_at), ?) "
+                    "WHERE id=?",
+                    (created, thread_id),
+                )
+            else:
+                existing_metadata = _loads(message["metadata_json"], {})
+                existing_run_id = (
+                    existing_metadata.get("researchRunId")
+                    if isinstance(existing_metadata, dict) else None
+                )
+                if (
+                    message["thread_id"] != thread_id
+                    or message["role"] != "assistant"
+                    or message["parent_id"] != user_message_id
+                    or existing_run_id not in (None, run_id)
+                ):
+                    raise ResearchConflictError(
+                        "Assistant message does not match this research run"
+                    )
+                merged_metadata = dict(existing_metadata) if isinstance(existing_metadata, dict) else {}
+                merged_metadata.update(metadata)
+                conn.execute(
+                    "UPDATE chat_messages SET metadata_json=? WHERE id=?",
+                    (json.dumps(merged_metadata, ensure_ascii = False), assistant_message_id),
+                )
+        conn.execute(
+            """
+            INSERT INTO research_runs
+                (id, owner_subject, thread_id, user_message_id, assistant_message_id,
+                 status, config_json, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, 'planning', ?, ?, ?)
+            """,
+            (run_id, owner_subject, thread_id, user_message_id, assistant_message_id,
+             json.dumps(config, ensure_ascii = False), created, created),
+        )
+        _event_locked(conn, run_id, "run.created", {"status": "planning"})
+        _commit_event(conn)
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+    return get_run(run_id, owner_subject)
+
+
+def _row_to_run(row: sqlite3.Row) -> dict[str, Any]:
+    data = dict(row)
+    return {
+        "id": data["id"], "ownerSubject": data["owner_subject"],
+        "threadId": data["thread_id"], "userMessageId": data["user_message_id"],
+        "assistantMessageId": data["assistant_message_id"], "status": data["status"],
+        "plan": _loads(data["plan_json"], None), "planRevision": data["plan_revision"],
+        "planHash": data["plan_hash"], "config": _loads(data["config_json"], {}),
+        "cancelRequested": bool(data["cancel_requested"]), "retryCount": data["retry_count"],
+        "error": data["error_message"], "report": data.get("report_text"),
+        "createdAt": data["created_at"],
+        "updatedAt": data["updated_at"], "startedAt": data["started_at"],
+        "completedAt": data["completed_at"], "heartbeatAt": data["heartbeat_at"],
+        "lastEventSeq": int(data["next_event_seq"]) - 1,
+    }
+
+
+def get_run(run_id: str, owner_subject: str | None = None) -> dict | None:
+    conn = get_connection()
+    try:
+        sql = "SELECT * FROM research_runs WHERE id = ?"
+        args: tuple = (run_id,)
+        if owner_subject is not None:
+            sql += " AND owner_subject = ?"
+            args += (owner_subject,)
+        row = conn.execute(sql, args).fetchone()
+        if row is None:
+            return None
+        result = _row_to_run(row)
+        result["steps"] = [dict(r) for r in conn.execute(
+            "SELECT position, title, query, status, result_json AS resultJson, "
+            "started_at AS startedAt, completed_at AS completedAt FROM research_plan_steps "
+            "WHERE run_id = ? ORDER BY position", (run_id,)
+        ).fetchall()]
+        for step in result["steps"]:
+            step["result"] = _loads(step.pop("resultJson"), None)
+            step["input"] = step["query"]
+        result["sources"] = [dict(r) for r in conn.execute(
+            "SELECT id, step_position AS stepPosition, url, title, snippet, "
+            "fetched_at AS fetchedAt FROM research_sources WHERE run_id = ? ORDER BY id",
+            (run_id,),
+        ).fetchall()]
+        return result
+    finally:
+        conn.close()
+
+
+def list_active(owner_subject: str, thread_id: str) -> list[dict]:
+    conn = get_connection()
+    try:
+        placeholders = ",".join("?" for _ in ACTIVE_STATUSES)
+        rows = conn.execute(
+            f"SELECT id FROM research_runs WHERE owner_subject = ? AND thread_id = ? "
+            f"AND status IN ({placeholders}) ORDER BY created_at",
+            (owner_subject, thread_id, *sorted(ACTIVE_STATUSES)),
+        ).fetchall()
+    finally:
+        conn.close()
+    return [run for row in rows if (run := get_run(row["id"], owner_subject)) is not None]
+
+
+def has_thread_claim(owner_subject: str, thread_id: str) -> bool:
+    conn = get_connection()
+    try:
+        return conn.execute(
+            "SELECT 1 FROM research_thread_claims "
+            "WHERE owner_subject=? AND thread_id=?",
+            (owner_subject, thread_id),
+        ).fetchone() is not None
+    finally:
+        conn.close()
+
+
+def _discover_assistant_locked(conn: sqlite3.Connection, run: sqlite3.Row) -> str | None:
+    bound_id = run["assistant_message_id"]
+    if bound_id:
+        bound = conn.execute(
+            "SELECT id FROM chat_messages WHERE id=? AND thread_id=? AND role='assistant'",
+            (bound_id, run["thread_id"]),
+        ).fetchone()
+        if bound is not None:
+            return str(bound["id"])
+    rows = conn.execute(
+        """SELECT id, metadata_json FROM chat_messages
+           WHERE thread_id=? AND parent_id=? AND role='assistant' ORDER BY created_at, id""",
+        (run["thread_id"], run["user_message_id"]),
+    ).fetchall()
+    for message in rows:
+        metadata = _loads(message["metadata_json"], {})
+        if isinstance(metadata, dict) and metadata.get("researchRunId") == run["id"]:
+            message_id = str(message["id"])
+            conn.execute(
+                "UPDATE research_runs SET assistant_message_id=?, updated_at=? WHERE id=?",
+                (message_id, now_ms(), run["id"]),
+            )
+            return message_id
+    return None
+
+
+def discover_and_bind_assistant_message(run_id: str) -> str | None:
+    """Atomically bind the assistant-ui child carrying this run's metadata."""
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        run = conn.execute("SELECT * FROM research_runs WHERE id=?", (run_id,)).fetchone()
+        if run is None:
+            raise KeyError(run_id)
+        message_id = _discover_assistant_locked(conn, run)
+        _commit_event(conn)
+        return message_id
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def create_and_bind_terminal_fallback(
+    run_id: str, *, text: str, status: str, sources: list[dict] | None = None,
+    completion_worker_id: str | None = None,
+) -> tuple[str, bool]:
+    """Discover a frontend message or atomically create exactly one fallback."""
+    if status not in TERMINAL_STATUSES:
+        raise ValueError(status)
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        run = conn.execute("SELECT * FROM research_runs WHERE id=?", (run_id,)).fetchone()
+        if run is None:
+            raise KeyError(run_id)
+        can_prepare_completion = (
+            completion_worker_id is not None
+            and status == "completed"
+            and run["status"] == "running"
+            and run["lease_owner"] == completion_worker_id
+            and run["lease_expires_at"] is not None
+            and int(run["lease_expires_at"]) >= now_ms()
+            and not bool(run["cancel_requested"])
+        )
+        if run["status"] != status and not can_prepare_completion:
+            raise ResearchConflictError(
+                f"Cannot create a {status} fallback for a {run['status']} run"
+            )
+        message_id = _discover_assistant_locked(conn, run)
+        if message_id is not None:
+            conn.commit()
+            return message_id, False
+
+        message_id = f"research-{run_id}"
+        parts: list[dict[str, Any]] = [
+            {"type": "text", "text": text, "researchRunId": run_id}
+        ]
+        for source in sources or []:
+            parts.append({
+                "type": "source", "sourceType": "url", "id": source["url"],
+                "url": source["url"], "title": source.get("title") or source["url"],
+                "metadata": {"description": source.get("snippet") or ""},
+                "researchRunId": run_id,
+            })
+        metadata = {
+            "researchRunId": run_id, "researchStatus": status,
+            "researchPlanRevision": int(run["plan_revision"]), "serverManaged": True,
+        }
+        created = now_ms()
+        conn.execute(
+            """INSERT INTO chat_messages
+               (id, thread_id, parent_id, role, content_json, metadata_json, created_at)
+               VALUES (?, ?, ?, 'assistant', ?, ?, ?)""",
+            (message_id, run["thread_id"], run["user_message_id"],
+             json.dumps(parts, ensure_ascii = False),
+             json.dumps(metadata, ensure_ascii = False), created),
+        )
+        conn.execute(
+            "UPDATE research_runs SET assistant_message_id=?, updated_at=? WHERE id=?",
+            (message_id, created, run_id),
+        )
+        conn.execute(
+            "UPDATE chat_threads SET updated_at=MAX(COALESCE(updated_at, created_at), ?) WHERE id=?",
+            (created, run["thread_id"]),
+        )
+        _commit_event(conn)
+        return message_id, True
+    except sqlite3.IntegrityError:
+        conn.rollback()
+        # A concurrent terminal path may have inserted the deterministic fallback.
+        message_id = discover_and_bind_assistant_message(run_id)
+        if message_id is None:
+            raise
+        return message_id, False
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def set_plan(
+    run_id: str, plan: dict, expected_revision: int | None = None,
+    worker_id: str | None = None,
+) -> dict:
+    raw, digest = canonical_plan(plan)
+    steps = plan.get("steps") or []
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute(
+            "SELECT status, plan_revision, lease_owner, lease_expires_at, cancel_requested "
+            "FROM research_runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        if row is None:
+            raise KeyError(run_id)
+        if worker_id is not None and (
+            row["status"] != "planning"
+            or row["lease_owner"] != worker_id
+            or row["lease_expires_at"] is None
+            or int(row["lease_expires_at"]) < now_ms()
+            or bool(row["cancel_requested"])
+        ):
+            raise ResearchConflictError("Planner no longer owns this research run")
+        if worker_id is None and row["status"] not in {"planning", "awaiting_approval"}:
+            raise ResearchConflictError("Plan can only be changed before approval")
+        revision = int(row["plan_revision"])
+        if expected_revision is not None and revision != expected_revision:
+            raise ResearchConflictError(f"Plan revision is {revision}, not {expected_revision}")
+        revision += 1
+        conn.execute(
+            "UPDATE research_runs SET plan_json = ?, plan_revision = ?, plan_hash = ?, "
+            "status = 'awaiting_approval', error_message = NULL, lease_owner = NULL, "
+            "lease_expires_at = NULL, updated_at = ? WHERE id = ?",
+            (raw, revision, digest, now_ms(), run_id),
+        )
+        conn.execute("DELETE FROM research_plan_steps WHERE run_id = ?", (run_id,))
+        conn.executemany(
+            "INSERT INTO research_plan_steps (run_id, position, title, query) VALUES (?, ?, ?, ?)",
+            [(run_id, i, str(s["title"]), str(s.get("query") or s["title"]))
+             for i, s in enumerate(steps)],
+        )
+        _event_locked(conn, run_id, "plan.ready", {
+            "status": "awaiting_approval", "plan": plan,
+            "planRevision": revision, "planHash": digest,
+        })
+        _commit_event(conn)
+        return {"plan": plan, "planRevision": revision, "planHash": digest}
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def approve(run_id: str, revision: int, plan_hash: str) -> str:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute(
+            "SELECT status, plan_revision, plan_hash FROM research_runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        if row is None:
+            raise KeyError(run_id)
+        if int(row["plan_revision"]) != revision or row["plan_hash"] != plan_hash:
+            raise ResearchConflictError("Plan revision or hash no longer matches")
+        if row["status"] in {"queued", "running", "completed"}:
+            conn.commit()
+            return row["status"]
+        if row["status"] != "awaiting_approval":
+            raise ResearchConflictError(f"Cannot approve a {row['status']} run")
+        conn.execute(
+            "UPDATE research_runs SET status = 'queued', updated_at = ? WHERE id = ?",
+            (now_ms(), run_id),
+        )
+        _event_locked(conn, run_id, "run.approved", {"status": "queued"})
+        _commit_event(conn)
+        return "queued"
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def request_cancel(run_id: str) -> str:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute("SELECT status FROM research_runs WHERE id = ?", (run_id,)).fetchone()
+        if row is None:
+            raise KeyError(run_id)
+        status = row["status"]
+        if status in TERMINAL_STATUSES or status == "cancelling":
+            conn.commit()
+            return status
+        new_status = "cancelled" if status in {"awaiting_approval", "queued", "paused"} else "cancelling"
+        completed = now_ms() if new_status == "cancelled" else None
+        conn.execute(
+            "UPDATE research_runs SET cancel_requested = 1, status = ?, completed_at = ?, "
+            "updated_at = ? WHERE id = ?", (new_status, completed, now_ms(), run_id),
+        )
+        event_type = "run.cancelled" if new_status == "cancelled" else "run.cancelRequested"
+        _event_locked(conn, run_id, event_type, {"status": new_status})
+        _commit_event(conn)
+        return new_status
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def retry(run_id: str, max_retries: int = 3) -> str:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute(
+            "SELECT status, retry_count, plan_json, owner_subject, thread_id "
+            "FROM research_runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        if row is None:
+            raise KeyError(run_id)
+        if row["status"] not in {"failed", "cancelled"}:
+            raise ResearchConflictError("Only failed or cancelled runs can be retried")
+        if int(row["retry_count"]) >= max_retries:
+            raise ResearchConflictError("Retry budget exhausted")
+        placeholders = ",".join("?" for _ in ACTIVE_STATUSES)
+        active = conn.execute(
+            f"SELECT id FROM research_runs WHERE owner_subject=? AND thread_id=? AND id<>? "
+            f"AND status IN ({placeholders}) LIMIT 1",
+            (row["owner_subject"], row["thread_id"], run_id, *sorted(ACTIVE_STATUSES)),
+        ).fetchone()
+        if active is not None:
+            raise ResearchConflictError("This thread already has an active research run")
+        plan_was_approved = False
+        if row["plan_json"]:
+            plan_was_approved = conn.execute(
+                "SELECT 1 FROM research_events WHERE run_id=? AND event_type='run.approved' LIMIT 1",
+                (run_id,),
+            ).fetchone() is not None
+        status = (
+            "queued" if plan_was_approved
+            else "awaiting_approval" if row["plan_json"]
+            else "planning"
+        )
+        conn.execute(
+            "UPDATE research_runs SET status = ?, cancel_requested = 0, retry_count = retry_count + 1, "
+            "error_message = NULL, report_text = NULL, completed_at = NULL, lease_owner = NULL, "
+            "lease_expires_at = NULL, updated_at = ? WHERE id = ?", (status, now_ms(), run_id),
+        )
+        if status != "awaiting_approval":
+            conn.execute("DELETE FROM research_plan_steps WHERE run_id = ?", (run_id,))
+        conn.execute("DELETE FROM research_sources WHERE run_id = ?", (run_id,))
+        _event_locked(conn, run_id, "run.retried", {"status": status})
+        _commit_event(conn)
+        return status
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def claim_next(worker_id: str, lease_ms: int = 120_000) -> dict | None:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        now = now_ms()
+        row = conn.execute(
+            """SELECT * FROM research_runs
+               WHERE status IN ('planning','queued','running','cancelling')
+                 AND (lease_owner IS NULL OR lease_expires_at < ?)
+               ORDER BY created_at LIMIT 1""", (now,),
+        ).fetchone()
+        if row is None:
+            conn.commit()
+            return None
+        status = row["status"]
+        next_status = (
+            "running" if status in {"queued", "running"}
+            else "cancelling" if status == "cancelling"
+            else "planning"
+        )
+        conn.execute(
+            "UPDATE research_runs SET status=?, lease_owner=?, lease_expires_at=?, heartbeat_at=?, "
+            "started_at=COALESCE(started_at, ?), updated_at=? WHERE id=?",
+            (next_status, worker_id, now + lease_ms, now, now, now, row["id"]),
+        )
+        _event_locked(conn, row["id"], "run.started", {"status": next_status})
+        _commit_event(conn)
+        return get_run(row["id"])
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def heartbeat(run_id: str, worker_id: str, lease_ms: int = 120_000) -> bool:
+    conn = get_connection()
+    try:
+        now = now_ms()
+        cur = conn.execute(
+            "UPDATE research_runs SET heartbeat_at=?, lease_expires_at=? "
+            "WHERE id=? AND lease_owner=? AND lease_expires_at>=?",
+            (now, now + lease_ms, run_id, worker_id, now),
+        )
+        conn.commit()
+        return cur.rowcount == 1
+    finally:
+        conn.close()
+
+
+def is_cancel_requested(run_id: str) -> bool:
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT cancel_requested FROM research_runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        return row is None or bool(row[0])
+    finally:
+        conn.close()
+
+
+def finish(
+    run_id: str, worker_id: str, status: str, error: str | None = None,
+    event_payload: dict[str, Any] | None = None, allow_expired: bool = False,
+) -> str | None:
+    if status not in TERMINAL_STATUSES:
+        raise ValueError(status)
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        now = now_ms()
+        row = conn.execute(
+            "SELECT status, cancel_requested, lease_expires_at "
+            "FROM research_runs WHERE id=? AND lease_owner=?",
+            (run_id, worker_id),
+        ).fetchone()
+        if row is None:
+            conn.commit()
+            return None
+        if (
+            not allow_expired
+            and not bool(row["cancel_requested"])
+            and (row["lease_expires_at"] is None or int(row["lease_expires_at"]) < now)
+        ):
+            conn.commit()
+            return None
+        actual_status = (
+            "cancelled"
+            if bool(row["cancel_requested"]) or row["status"] == "cancelling"
+            else status
+        )
+        actual_error = None if actual_status == "cancelled" else error
+        report_text = None
+        if actual_status == "completed" and event_payload:
+            candidate = event_payload.get("report")
+            if isinstance(candidate, str):
+                report_text = candidate
+        conn.execute(
+            "UPDATE research_runs SET status=?, error_message=?, report_text=?, completed_at=?, updated_at=?, "
+            "lease_owner=NULL, lease_expires_at=NULL WHERE id=? AND lease_owner=?",
+            (actual_status, actual_error, report_text, now, now, run_id, worker_id),
+        )
+        payload = {"status": actual_status, "error": actual_error}
+        if event_payload and actual_status == status:
+            payload.update(event_payload)
+        _event_locked(conn, run_id, f"run.{actual_status}", payload)
+        _commit_event(conn)
+        return actual_status
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def set_report_progress(
+    run_id: str, report: str, delta: str | None = None,
+    worker_id: str | None = None,
+) -> bool:
+    """Persist partial report text and notify followers while synthesis runs."""
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute(
+            "SELECT status, lease_owner, lease_expires_at, cancel_requested "
+            "FROM research_runs WHERE id = ?",
+            (run_id,),
+        ).fetchone()
+        if (
+            row is None
+            or row["status"] != "running"
+            or worker_id is not None and (
+                row["lease_owner"] != worker_id or bool(row["cancel_requested"])
+                or row["lease_expires_at"] is None
+                or int(row["lease_expires_at"]) < now_ms()
+            )
+        ):
+            conn.commit()
+            return False
+        now = now_ms()
+        conn.execute(
+            "UPDATE research_runs SET report_text = ?, updated_at = ? WHERE id = ?",
+            (report, now, run_id),
+        )
+        event_data: dict[str, Any] = {"length": len(report)}
+        if delta:
+            event_data.update({"delta": delta, "offset": len(report) - len(delta)})
+        _event_locked(conn, run_id, "report.updated", event_data)
+        _commit_event(conn)
+        return True
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def update_step(run_id: str, position: int, status: str, result: Any = None) -> None:
+    conn = get_connection()
+    try:
+        now = now_ms()
+        conn.execute(
+            "UPDATE research_plan_steps SET status=?, result_json=?, "
+            "started_at=CASE WHEN ?='running' THEN COALESCE(started_at, ?) ELSE started_at END, "
+            "completed_at=CASE WHEN ? IN ('completed','failed') THEN ? ELSE completed_at END "
+            "WHERE run_id=? AND position=?",
+            (status, json.dumps(result, ensure_ascii = False) if result is not None else None,
+             status, now, status, now, run_id, position),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def reset_execution_steps(run_id: str, worker_id: str | None = None) -> bool:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        if worker_id is not None and not _worker_can_write_locked(
+            conn, run_id, worker_id, {"running"},
+        ):
+            conn.commit()
+            return False
+        conn.execute("DELETE FROM research_plan_steps WHERE run_id = ?", (run_id,))
+        conn.commit()
+        return True
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def upsert_execution_step(
+    run_id: str, position: int, title: str, query: str, status: str,
+    result: Any = None, worker_id: str | None = None,
+) -> bool:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        if worker_id is not None and not _worker_can_write_locked(
+            conn, run_id, worker_id, {"running"},
+        ):
+            conn.commit()
+            return False
+        now = now_ms()
+        conn.execute(
+            """INSERT INTO research_plan_steps
+               (run_id, position, title, query, status, result_json, started_at, completed_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+               ON CONFLICT(run_id, position) DO UPDATE SET
+                 title=excluded.title, query=excluded.query, status=excluded.status,
+                 result_json=excluded.result_json,
+                 started_at=COALESCE(research_plan_steps.started_at, excluded.started_at),
+                 completed_at=excluded.completed_at""",
+            (
+                run_id, position, title[:200], query[:500], status,
+                json.dumps(result, ensure_ascii = False) if result is not None else None,
+                now, now if status in {"completed", "failed"} else None,
+            ),
+        )
+        conn.commit()
+        return True
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def get_reasoning_text(run_id: str) -> str:
+    conn = get_connection()
+    try:
+        run = conn.execute(
+            "SELECT retry_count FROM research_runs WHERE id=?", (run_id,)
+        ).fetchone()
+        if run is None:
+            return ""
+        attempt = int(run["retry_count"])
+        rows = conn.execute(
+            "SELECT data_json FROM research_events WHERE run_id=? "
+            "AND event_type='reasoning.updated' ORDER BY seq",
+            (run_id,),
+        ).fetchall()
+        return "".join(
+            str(data.get("reasoningDelta") or "")
+            for row in rows
+            if int((data := _loads(row["data_json"], {})).get("attempt", 0)) == attempt
+        )
+    finally:
+        conn.close()
+
+
+def upsert_source(
+    run_id: str, position: int, url: str, title: str, snippet: str,
+    worker_id: str | None = None,
+) -> bool:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        if worker_id is not None and not _worker_can_write_locked(
+            conn, run_id, worker_id, {"running"},
+        ):
+            conn.commit()
+            return False
+        run = conn.execute(
+            "SELECT config_json FROM research_runs WHERE id=?", (run_id,),
+        ).fetchone()
+        if run is None:
+            conn.commit()
+            return False
+        config = _loads(run["config_json"], {})
+        allowed, reason, _hostname = check_url_access(
+            url, config.get("websitePolicy") if isinstance(config, dict) else None,
+        )
+        if not allowed:
+            raise ValueError(reason)
+        fetched_at = now_ms()
+        conn.execute(
+            """INSERT INTO research_sources (run_id, step_position, url, title, snippet, fetched_at)
+               VALUES (?, ?, ?, ?, ?, ?)
+               ON CONFLICT(run_id, url) DO UPDATE SET step_position=excluded.step_position,
+               title=excluded.title,
+               snippet=excluded.snippet, fetched_at=excluded.fetched_at""",
+            (run_id, position, url, title[:500], snippet[:4000], fetched_at),
+        )
+        _event_locked(conn, run_id, "source.added", {
+            "position": position, "stepPosition": position, "url": url,
+            "title": title[:500], "snippet": snippet[:4000], "fetchedAt": fetched_at,
+        })
+        _commit_event(conn)
+        return True
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def list_events(run_id: str, owner_subject: str, after: int = 0, limit: int = 1000) -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            """SELECT e.seq, e.event_type, e.data_json, e.created_at
+               FROM research_events e JOIN research_runs r ON r.id=e.run_id
+               WHERE e.run_id=? AND r.owner_subject=? AND e.seq>? ORDER BY e.seq LIMIT ?""",
+            (run_id, owner_subject, after, limit),
+        ).fetchall()
+        return [{"seq": r["seq"], "type": r["event_type"],
+                 "data": _loads(r["data_json"], {}), "createdAt": r["created_at"]} for r in rows]
+    finally:
+        conn.close()
+
+
+def wait_for_events(
+    run_id: str, owner_subject: str, after: int = 0, timeout: float = 15,
+) -> list[dict]:
+    """Block until committed events are available or the keep-alive timeout expires."""
+    events = list_events(run_id, owner_subject, after)
+    if events:
+        return events
+    with _EVENTS_CHANGED:
+        # Recheck under the condition lock so a commit cannot be missed between
+        # the initial query and waiting for its notification.
+        events = list_events(run_id, owner_subject, after)
+        if events:
+            return events
+        _EVENTS_CHANGED.wait(timeout)
+    return list_events(run_id, owner_subject, after)
+
+
+def recover_expired(now: int | None = None) -> int:
+    conn = get_connection()
+    try:
+        now = now or now_ms()
+        cur = conn.execute(
+            """UPDATE research_runs SET lease_owner=NULL, lease_expires_at=NULL, updated_at=?
+               WHERE status IN ('planning','queued','running','cancelling')
+                 AND lease_owner IS NOT NULL AND lease_expires_at < ?""", (now, now),
+        )
+        conn.commit()
+        return cur.rowcount
+    finally:
+        conn.close()
+
+
+def owns_lease(run_id: str, worker_id: str) -> bool:
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM research_runs WHERE id=? AND lease_owner=? AND lease_expires_at>=?",
+            (run_id, worker_id, now_ms()),
+        ).fetchone()
+        return row is not None
+    finally:
+        conn.close()
+
+
+def release_worker_leases(worker_id: str) -> int:
+    conn = get_connection()
+    try:
+        cur = conn.execute(
+            """UPDATE research_runs SET lease_owner=NULL, lease_expires_at=NULL, updated_at=?
+               WHERE lease_owner=? AND status IN ('planning','queued','running','cancelling')""",
+            (now_ms(), worker_id),
+        )
+        conn.commit()
+        return cur.rowcount
+    finally:
+        conn.close()

studio/backend/storage/studio_db.py

@@ -391,6 +391,110 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_prompt_lists_created_at ON prompt_lists(created_at)"
     )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS research_runs (
+            id TEXT NOT NULL PRIMARY KEY,
+            owner_subject TEXT NOT NULL,
+            thread_id TEXT NOT NULL REFERENCES chat_threads(id) ON DELETE CASCADE,
+            user_message_id TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,
+            assistant_message_id TEXT REFERENCES chat_messages(id) ON DELETE SET NULL,
+            status TEXT NOT NULL CHECK(status IN (
+                'planning', 'awaiting_approval', 'queued', 'running', 'paused',
+                'cancelling', 'cancelled', 'completed', 'failed'
+            )),
+            plan_json TEXT,
+            plan_revision INTEGER NOT NULL DEFAULT 0,
+            plan_hash TEXT,
+            config_json TEXT NOT NULL,
+            cancel_requested INTEGER NOT NULL DEFAULT 0,
+            lease_owner TEXT,
+            lease_expires_at INTEGER,
+            heartbeat_at INTEGER,
+            retry_count INTEGER NOT NULL DEFAULT 0,
+            error_message TEXT,
+            report_text TEXT,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL,
+            started_at INTEGER,
+            completed_at INTEGER,
+            next_event_seq INTEGER NOT NULL DEFAULT 1
+        )
+        """
+    )
+    research_run_cols = {
+        row[1] for row in conn.execute("PRAGMA table_info(research_runs)").fetchall()
+    }
+    if "report_text" not in research_run_cols:
+        conn.execute("ALTER TABLE research_runs ADD COLUMN report_text TEXT")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS research_thread_claims (
+            owner_subject TEXT NOT NULL,
+            thread_id TEXT NOT NULL REFERENCES chat_threads(id) ON DELETE CASCADE,
+            created_at INTEGER NOT NULL,
+            PRIMARY KEY(owner_subject, thread_id)
+        ) WITHOUT ROWID
+        """
+    )
+    conn.execute(
+        """INSERT OR IGNORE INTO research_thread_claims
+           (owner_subject, thread_id, created_at)
+           SELECT owner_subject, thread_id, MIN(created_at)
+           FROM research_runs GROUP BY owner_subject, thread_id"""
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS research_plan_steps (
+            run_id TEXT NOT NULL REFERENCES research_runs(id) ON DELETE CASCADE,
+            position INTEGER NOT NULL,
+            title TEXT NOT NULL,
+            query TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            result_json TEXT,
+            started_at INTEGER,
+            completed_at INTEGER,
+            PRIMARY KEY(run_id, position)
+        ) WITHOUT ROWID
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS research_sources (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            run_id TEXT NOT NULL REFERENCES research_runs(id) ON DELETE CASCADE,
+            step_position INTEGER,
+            url TEXT NOT NULL,
+            title TEXT,
+            snippet TEXT,
+            fetched_at INTEGER NOT NULL,
+            UNIQUE(run_id, url)
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS research_events (
+            run_id TEXT NOT NULL REFERENCES research_runs(id) ON DELETE CASCADE,
+            seq INTEGER NOT NULL,
+            event_type TEXT NOT NULL,
+            data_json TEXT NOT NULL,
+            created_at INTEGER NOT NULL,
+            PRIMARY KEY(run_id, seq)
+        ) WITHOUT ROWID
+        """
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_research_runs_owner_thread_status "
+        "ON research_runs(owner_subject, thread_id, status)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_research_runs_lease "
+        "ON research_runs(status, lease_expires_at)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_research_sources_run ON research_sources(run_id, id)"
+    )
 
 
 def _prompt_entry_from_row(row: sqlite3.Row) -> dict:

studio/backend/tests/test_web_access_policy.py

@@ -0,0 +1,177 @@
+# 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 sys
+import urllib.error
+from email.message import Message
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import tools
+from core.inference.web_access_policy import (
+    check_url_access,
+    normalize_website_policy,
+    scope_search_query,
+    website_policy_prompt,
+)
+from routes.research_runs import CreateResearchRun, _sanitize_config
+
+
+ARXIV_ONLY = {"allowedDomains": ["arxiv.org"], "blockedDomains": []}
+
+
+def test_create_run_normalizes_and_persists_website_policy():
+    payload = CreateResearchRun(
+        threadId = "thread", userMessageId = "message",
+        inferenceRequest = {"model": "local-model"},
+        websitePolicy = {
+            "allowedDomains": ["ARXIV.ORG."],
+            "blockedDomains": ["ads.arxiv.org"],
+        },
+    )
+    config = _sanitize_config(payload, {"modelId": "local-model"})
+    assert config["websitePolicy"] == {
+        "allowedDomains": ["arxiv.org"],
+        "blockedDomains": ["ads.arxiv.org"],
+    }
+
+
+@pytest.mark.parametrize(
+    ("url", "allowed"),
+    [
+        ("https://arxiv.org/abs/2601.00001", True),
+        ("https://export.arxiv.org/api/query", True),
+        ("https://arxiv.org.evil.example/paper", False),
+        ("https://arxiv.org@evil.example/paper", False),
+        ("https://evil.example/?next=arxiv.org", False),
+        ("https://arxiv.org%2eevil.example/paper", False),
+        ("https://134744072/paper", False),
+        ("https://010.010.010.010/paper", False),
+    ],
+)
+def test_allowlist_matches_parsed_domain_boundaries(url, allowed):
+    assert check_url_access(url, ARXIV_ONLY)[0] is allowed
+
+
+def test_blacklist_takes_precedence_and_covers_subdomains():
+    policy = {
+        "allowedDomains": ["example.org"],
+        "blockedDomains": ["private.example.org"],
+    }
+    assert check_url_access("https://www.example.org", policy)[0]
+    assert not check_url_access("https://private.example.org", policy)[0]
+    assert not check_url_access("https://a.private.example.org", policy)[0]
+
+
+def test_public_ipv6_literals_are_normalized_for_policy_matching():
+    ipv6 = "2606:4700:4700::1111"
+    policy = {"allowedDomains": [ipv6], "blockedDomains": []}
+    assert check_url_access(f"https://[{ipv6}]/", policy) == (True, "", ipv6)
+
+
+@pytest.mark.parametrize("hostname", ["134744072", "010.010.010.010", "0x08080808"])
+def test_noncanonical_numeric_ip_hostnames_are_always_rejected(hostname):
+    assert not check_url_access(f"https://{hostname}/", None)[0]
+
+
+def test_policy_normalizes_idna_deduplicates_and_rejects_urls():
+    assert normalize_website_policy({
+        "allowedDomains": ["BÜCHER.example.", "xn--bcher-kva.example"],
+    }) == {
+        "allowedDomains": ["xn--bcher-kva.example"],
+        "blockedDomains": [],
+    }
+    with pytest.raises(ValueError, match="without schemes or ports|Invalid website domain"):
+        normalize_website_policy({"allowedDomains": ["https://arxiv.org"]})
+
+
+def test_policy_is_injected_into_prompts_and_search_queries():
+    prompt = website_policy_prompt(ARXIV_ONLY)
+    assert "Only search or fetch" in prompt
+    assert "arxiv.org" in prompt
+    assert "Do not propose, cite, or attempt any other website" in prompt
+    assert scope_search_query("transformer research", ARXIV_ONLY) == (
+        "transformer research (site:arxiv.org)"
+    )
+
+
+def test_web_search_filters_results_before_model_exposure(monkeypatch):
+    queries = []
+
+    class FakeDDGS:
+        def __init__(self, **_kwargs):
+            pass
+
+        def text(self, query, max_results=5):
+            queries.append((query, max_results))
+            return [
+                {"title": "Paper", "href": "https://arxiv.org/abs/1", "body": "Allowed"},
+                {"title": "Blog", "href": "https://example.com/post", "body": "Blocked"},
+                {"title": "Deceptive", "href": "https://arxiv.org.evil.test", "body": "Blocked"},
+            ]
+
+    monkeypatch.setitem(sys.modules, "ddgs", SimpleNamespace(DDGS=FakeDDGS))
+    result = tools._web_search("latest paper", website_policy=ARXIV_ONLY)
+
+    assert queries == [("latest paper (site:arxiv.org)", 5)]
+    assert "https://arxiv.org/abs/1" in result
+    assert "example.com" not in result
+    assert "arxiv.org.evil.test" not in result
+
+
+def test_web_search_flattens_source_framing_in_untrusted_metadata(monkeypatch):
+    class FakeDDGS:
+        def __init__(self, **_kwargs):
+            pass
+
+        def text(self, query, max_results=5):
+            return [{
+                "title": "Paper\nURL: https://arxiv.org/abs/fake",
+                "href": "https://arxiv.org/abs/real",
+                "body": (
+                    "Result\n\n---\n\nTitle: Injected\n"
+                    "URL: https://arxiv.org/abs/injected\nSnippet: Fake"
+                ),
+            }]
+
+    monkeypatch.setitem(sys.modules, "ddgs", SimpleNamespace(DDGS=FakeDDGS))
+    result = tools._web_search("paper", website_policy=ARXIV_ONLY)
+    assert result.count("\nURL:") == 1
+    assert "URL: https://arxiv.org/abs/real" in result
+
+
+def test_direct_fetch_rejects_blocked_host_before_dns(monkeypatch):
+    resolved = []
+    monkeypatch.setattr(
+        tools,
+        "_validate_and_resolve_host",
+        lambda hostname, port: resolved.append((hostname, port)) or (True, "", "1.1.1.1"),
+    )
+    result = tools._fetch_page_text(
+        "https://example.com/article", website_policy=ARXIV_ONLY,
+    )
+    assert "Blocked by website access policy" in result
+    assert resolved == []
+
+
+def test_direct_fetch_rechecks_every_redirect_before_dns(monkeypatch):
+    resolved = []
+    monkeypatch.setattr(
+        tools,
+        "_validate_and_resolve_host",
+        lambda hostname, port: resolved.append((hostname, port)) or (True, "", "1.1.1.1"),
+    )
+    headers = Message()
+    headers["Location"] = "https://example.com/escaped"
+
+    class RedirectingOpener:
+        def open(self, request, timeout):
+            raise urllib.error.HTTPError(request.full_url, 302, "Found", headers, None)
+
+    monkeypatch.setattr(tools.urllib.request, "build_opener", lambda *_args: RedirectingOpener())
+    result = tools._fetch_page_text(
+        "https://arxiv.org/abs/1", website_policy=ARXIV_ONLY,
+    )
+    assert "Blocked by website access policy: example.com" in result
+    assert resolved == [("arxiv.org", 443)]

studio/frontend/src/components/assistant-ui/sources.tsx

@@ -126,7 +126,7 @@ function Source({
 
 // ── Source badge with hover card ─────────────────────────────
 
-interface SourceData {
+export interface SourceData {
   /**
    * Stable per-citation key. Two Anthropic citations into different spans of
    * the same source share a `url`, so React keys on `id` to keep them distinct.
@@ -178,14 +178,16 @@ const SourceBadge: FC<{ source: SourceData }> = ({ source }) => {
 
 // ── Grouped sources with 2-row collapse ─────────────────────
 
-const SourcesGroup: FC = () => {
+const SourcesGroup: FC<{ sources?: SourceData[] }> = ({
+  sources: suppliedSources,
+}) => {
   const message = useMessage();
   const containerRef = useRef<HTMLDivElement>(null);
   const [visibleCount, setVisibleCount] = useState<number | null>(null);
   const [expanded, setExpanded] = useState(false);
 
-  const sources: SourceData[] = [];
-  if (message.content) {
+  const messageSources: SourceData[] = [];
+  if (!suppliedSources && message.content) {
     for (const part of message.content) {
       if (
         part.type === "source" &&
@@ -199,7 +201,7 @@ const SourcesGroup: FC = () => {
           typeof (part as { id?: unknown }).id === "string"
             ? ((part as { id: string }).id)
             : url;
-        sources.push({
+        messageSources.push({
           id: partId,
           url,
           title: (part as { title?: string }).title || "",
@@ -209,6 +211,7 @@ const SourcesGroup: FC = () => {
       }
     }
   }
+  const sources = suppliedSources ?? messageSources;
 
   // Measure how many badges fit in 2 rows
   const measure = useCallback(() => {

studio/frontend/src/components/assistant-ui/thread.tsx

@@ -74,6 +74,16 @@ import {
 import { useChatPreferencesStore } from "@/features/chat/stores/chat-preferences-store";
 import { useChatProjects } from "@/features/chat/hooks/use-chat-projects";
 import { NewProjectDialog } from "@/features/chat/components/new-project-dialog";
+import { ResearchMessage } from "@/features/chat/components/research-message";
+import {
+  DeepResearchComposerButton,
+  DeepResearchWebsiteAccessDialog,
+} from "@/features/chat/components/deep-research-composer-button";
+import { cancelResearchRun } from "@/features/chat/api/research-api";
+import {
+  ingestResearchUpdate,
+  useResearchRunStore,
+} from "@/features/chat/stores/research-run-store";
 import { parseExternalModelId } from "@/features/chat/external-providers";
 import { McpComposerButton } from "@/features/chat/mcp-composer-button";
 import { getExternalReasoningCapabilities } from "@/features/chat/provider-capabilities";
@@ -151,6 +161,7 @@ import {
   PlusIcon,
   RefreshCwIcon,
   SquareIcon,
+  TelescopeIcon,
   TerminalIcon,
   Volume2Icon,
   VolumeXIcon,
@@ -1435,6 +1446,37 @@ const Composer: FC<{
   const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
   const permissionMode = useChatRuntimeStore((s) => s.permissionMode);
+  const deepResearchEnabled = useChatRuntimeStore(
+    (s) => s.deepResearchEnabled,
+  );
+  const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
+  const researchThreadId = threadId ?? activeThreadId ?? null;
+  const researchThreadClaimed = useResearchRunStore((state) =>
+    researchThreadId ? Boolean(state.claimedThreadIds[researchThreadId]) : false,
+  );
+  const hasResearchMessage = useAuiState(({ thread }) =>
+    thread.messages.some((message) => {
+      const custom = (
+        message.metadata as
+          | { custom?: { researchRunId?: unknown } }
+          | undefined
+      )?.custom;
+      return typeof custom?.researchRunId === "string";
+    }),
+  );
+  const researchUsed = researchThreadClaimed || hasResearchMessage;
+  const effectiveDeepResearchEnabled = deepResearchEnabled && !researchUsed;
+  const [researchWebsiteAccessOpen, setResearchWebsiteAccessOpen] =
+    useState(false);
+  useEffect(() => {
+    if (!researchUsed) return;
+    if (hasResearchMessage && researchThreadId) {
+      useResearchRunStore.getState().setThreadClaimed(researchThreadId, true);
+    }
+    if (deepResearchEnabled) {
+      useChatRuntimeStore.getState().setDeepResearchEnabled(false);
+    }
+  }, [deepResearchEnabled, hasResearchMessage, researchThreadId, researchUsed]);
   // More than 4 pills: collapse to icons only. Search and Code always show; the
   // permission pill shows in every mode except "off" (it renders null there);
   // Images, RAG, Canvas and MCP are conditional.
@@ -1444,9 +1486,9 @@ const Composer: FC<{
       (ragEnabled ? 1 : 0) +
       (supportsBuiltinImageGeneration ? 1 : 0) +
       (artifactsEnabled ? 1 : 0) +
-      (mcpEnabledForChat ? 1 : 0) >
+      (mcpEnabledForChat ? 1 : 0) +
+      (effectiveDeepResearchEnabled ? 1 : 0) >
     4;
-  const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const setPendingImageEditReference = useChatRuntimeStore(
     (s) => s.setPendingImageEditReference,
   );
@@ -1569,6 +1611,7 @@ const Composer: FC<{
     ragEnabled ||
     artifactsEnabled ||
     mcpEnabledForChat ||
+    effectiveDeepResearchEnabled ||
     permissionMode !== "off";
   // react-textarea-autosize re-measures only on value change or window resize,
   // not on the width swap from expanding, so it keeps the taller height and
@@ -1862,10 +1905,18 @@ const Composer: FC<{
           className="unsloth-composer-left"
           data-pill-compact={pillsCompact ? "true" : undefined}
         >
-          <ComposerToolsMenu side={effectiveMenuSide} />
+          <ComposerToolsMenu
+            side={effectiveMenuSide}
+            researchAvailable={!researchUsed}
+          />
           {/* Permission-level pill: always visible, even while the pill row
               is collapsed; opens the permission level dropdown. */}
           <PermissionModeComposerPill side={effectiveMenuSide} />
+          {effectiveDeepResearchEnabled ? (
+            <DeepResearchComposerButton
+              onConfigure={() => setResearchWebsiteAccessOpen(true)}
+            />
+          ) : null}
           {composerExpanded ? (
             <>
               <WebSearchToggle />
@@ -1920,6 +1971,10 @@ const Composer: FC<{
           queueThreadIds={promptQueueThreadIds}
         />
       </div>
+      <DeepResearchWebsiteAccessDialog
+        open={researchWebsiteAccessOpen && effectiveDeepResearchEnabled}
+        onOpenChange={setResearchWebsiteAccessOpen}
+      />
     </>
   );
 
@@ -2699,9 +2754,10 @@ function attachmentAcceptForPicker(accept: string, audioEnabled: boolean): strin
   return filtered || accept;
 }
 
-const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
-  side = "bottom",
-}) => {
+const ComposerToolsMenu: FC<{
+  side?: "top" | "bottom";
+  researchAvailable: boolean;
+}> = ({ side = "bottom", researchAvailable }) => {
   const navigate = useNavigate();
   const toolsEnabled = useChatRuntimeStore((s) => s.toolsEnabled);
   const setToolsEnabled = useChatRuntimeStore((s) => s.setToolsEnabled);
@@ -2714,6 +2770,9 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const setMcpEnabledForChat = useChatRuntimeStore(
     (s) => s.setMcpEnabledForChat,
   );
+  const deepResearchEnabled = useChatRuntimeStore((s) => s.deepResearchEnabled);
+  const setDeepResearchEnabled = useChatRuntimeStore((s) => s.setDeepResearchEnabled);
+  const incognito = useChatRuntimeStore((s) => s.incognito);
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
   const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
   // Shared gate so the menu row agrees with the RAG pill.
@@ -2767,6 +2826,9 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const imageDisabled = !modelLoaded;
   // Like Search/Code: disabled only when a loaded model lacks tool support.
   const mcpDisabled = modelLoaded && !supportsTools;
+  // Match Search and Code: allow pre-selection before a local model loads.
+  const researchDisabled =
+    !researchAvailable || Boolean(externalSelection) || incognito;
   // Three most recently updated projects for the quick-access submenu.
   const { projects } = useChatProjects();
   const recentProjects = [...projects]
@@ -2792,7 +2854,6 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const [newProjectOpen, setNewProjectOpen] = useState(false);
   const [promptStorageOpen, setPromptStorageOpen] = useState(false);
   const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
-  const incognito = useChatRuntimeStore((s) => s.incognito);
   const aui = useAui();
   const composerCanAddAttachments = useAuiState(
     ({ composer }) => composer.isEditing,
@@ -3052,6 +3113,27 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
           <HugeiconsIcon icon={AttachmentIcon} strokeWidth={2} />
           Add photos &amp; files
         </DropdownMenuItem>
+        {researchAvailable ? (
+          <DropdownMenuItem
+            disabled={researchDisabled && !deepResearchEnabled}
+            className={
+              deepResearchEnabled && !researchDisabled
+                ? "text-primary font-medium"
+                : undefined
+            }
+            onSelect={() => setDeepResearchEnabled(!deepResearchEnabled)}
+          >
+            <TelescopeIcon />
+            Deep research
+            {deepResearchEnabled && !researchDisabled ? (
+              <HugeiconsIcon
+                icon={Tick02Icon}
+                strokeWidth={2}
+                className="ml-auto"
+              />
+            ) : null}
+          </DropdownMenuItem>
+        ) : null}
         <DropdownMenuItem
           disabled={searchDisabled}
           className={
@@ -3352,6 +3434,60 @@ const ComposerRightControls: FC<{
     findPromptQueueEntry(s, queueThreadIds),
   );
   const isQueueRunning = Boolean(queueEntry);
+  const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const activeResearchRun = useResearchRunStore((state) => {
+    const runId = activeThreadId
+      ? state.latestRunByThreadId[activeThreadId]
+      : undefined;
+    return runId ? state.sessions[runId]?.run : undefined;
+  });
+  const isResearchActive = Boolean(
+    activeResearchRun &&
+      !["completed", "failed", "cancelled"].includes(activeResearchRun.status),
+  );
+  const [stoppingResearchRunId, setStoppingResearchRunId] = useState<
+    string | null
+  >(null);
+  const stoppingResearchRunIdRef = useRef<string | null>(null);
+  const researchStopping = Boolean(
+    activeResearchRun &&
+      (activeResearchRun.status === "cancelling" ||
+        stoppingResearchRunId === activeResearchRun.id),
+  );
+  useEffect(() => {
+    if (
+      !isResearchActive ||
+      (stoppingResearchRunIdRef.current &&
+        stoppingResearchRunIdRef.current !== activeResearchRun?.id)
+    ) {
+      stoppingResearchRunIdRef.current = null;
+      setStoppingResearchRunId(null);
+    }
+  }, [activeResearchRun?.id, isResearchActive]);
+  const stop = () => {
+    if (isResearchActive && activeResearchRun) {
+      if (
+        activeResearchRun.status === "cancelling" ||
+        stoppingResearchRunIdRef.current === activeResearchRun.id
+      ) {
+        return;
+      }
+      if (isQueueRunning) onStopClick?.();
+      stoppingResearchRunIdRef.current = activeResearchRun.id;
+      setStoppingResearchRunId(activeResearchRun.id);
+      void cancelResearchRun(activeResearchRun.id)
+        .then((run) => ingestResearchUpdate(run))
+        .catch((error) => {
+          stoppingResearchRunIdRef.current = null;
+          setStoppingResearchRunId(null);
+          toast.error("Could not stop research", {
+            description: error instanceof Error ? error.message : undefined,
+          });
+        });
+      return;
+    }
+    if (isQueueRunning) onStopClick?.();
+  };
   return (
     <div className="aui-composer-action-wrapper flex shrink-0 items-center gap-1.5">
       <ReasoningToggle side={menuSide} />
@@ -3379,7 +3515,11 @@ const ComposerRightControls: FC<{
           </TooltipIconButton>
         </ComposerPrimitive.StopDictation>
       </ComposerPrimitive.If>
-      <AuiIf condition={({ thread }) => !thread.isRunning && !isQueueRunning}>
+      <AuiIf
+        condition={({ thread }) =>
+          !thread.isRunning && !isQueueRunning && !isResearchActive
+        }
+      >
         <ComposerPrimitive.Send asChild={true}>
           <TooltipIconButton
             tooltip={pendingSend ? "Waiting for documents…" : "Send message"}
@@ -3402,7 +3542,7 @@ const ComposerRightControls: FC<{
           </TooltipIconButton>
         </ComposerPrimitive.Send>
       </AuiIf>
-      {isQueueRunning ? (
+      {isQueueRunning && !isResearchActive ? (
         <AuiIf condition={({ thread }) => !thread.isRunning}>
           <TooltipIconButton
             tooltip="Queue message"
@@ -3419,9 +3559,26 @@ const ComposerRightControls: FC<{
           </TooltipIconButton>
         </AuiIf>
       ) : null}
-      <AuiIf condition={({ thread }) => thread.isRunning}>
-        <div className="ml-1.5 flex items-center">
-          {queueDisabled ? (
+      {isResearchActive ? (
+        <Button
+          type="button"
+          variant="default"
+          size="icon"
+          className="aui-composer-cancel ml-1.5 size-8 rounded-full"
+          aria-label={researchStopping ? "Stopping research" : "Stop research"}
+          disabled={researchStopping}
+          onClick={stop}
+        >
+          {researchStopping ? (
+            <Spinner className="size-3.5" />
+          ) : (
+            <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
+          )}
+        </Button>
+      ) : (
+        <AuiIf condition={({ thread }) => thread.isRunning}>
+          <div className="ml-1.5 flex items-center">
+            {queueDisabled ? (
             <ComposerPrimitive.Cancel asChild={true}>
               <Button
                 type="button"
@@ -3429,12 +3586,12 @@ const ComposerRightControls: FC<{
                 size="icon"
                 className="aui-composer-cancel size-8 rounded-full"
                 aria-label="Stop generating"
-                onClick={isQueueRunning ? onStopClick : undefined}
+                onClick={stop}
               >
                 <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
               </Button>
             </ComposerPrimitive.Cancel>
-          ) : (
+            ) : (
             <TooltipIconButton
               tooltip="Queue message"
               side="bottom"
@@ -3448,9 +3605,10 @@ const ComposerRightControls: FC<{
             >
               <ArrowUpIcon className="aui-composer-send-icon size-[21px] stroke-2" />
             </TooltipIconButton>
-          )}
-        </div>
-      </AuiIf>
+            )}
+          </div>
+        </AuiIf>
+      )}
     </div>
   );
 };
@@ -3560,6 +3718,16 @@ const AssistantMessage: FC = () => {
   const aui = useAui();
   const messageId = useAuiState(({ message }) => message.id);
   const messageContent = useAuiState(({ message }) => message.content);
+  const researchRunId = useAuiState(({ message }) => {
+    const custom = (
+      message.metadata as
+        | { custom?: { researchRunId?: unknown } }
+        | undefined
+    )?.custom;
+    return typeof custom?.researchRunId === "string"
+      ? custom.researchRunId
+      : null;
+  });
   const incognito = useChatRuntimeStore((s) => s.incognito);
 
   // Use global store for editing state to ensure a single source of truth
@@ -3648,16 +3816,20 @@ const AssistantMessage: FC = () => {
             <div className="pointer-events-none relative h-0 min-w-0">
               <MessageResponseModelBadge className="absolute -top-6 left-0 max-w-[min(22rem,100%)]" />
             </div>
-            <GeneratingIndicator />
-            <CancelledIndicator />
-            <DiffusionCanvas />
+            {researchRunId ? (
+              <ResearchMessage />
+            ) : (
+              <>
+                <GeneratingIndicator />
+                <CancelledIndicator />
+                <DiffusionCanvas />
 
             {/*
                 We use the standard MessagePrimitive.Parts. This ensures that
                 edited messages maintain the same professional styling,
                 Markdown rendering, and tool-call components as original responses.
             */}
-            <MessagePrimitive.Parts
+                <MessagePrimitive.Parts
               components={{
                 Text: MarkdownText,
                 Reasoning: Reasoning,
@@ -3677,10 +3849,12 @@ const AssistantMessage: FC = () => {
                   Fallback: ToolFallbackConfirmable,
                 },
               }}
-            />
-            <SourcesGroup />
-            <RagSourcesGroup />
-            <MessageHtmlArtifacts />
+                />
+                <SourcesGroup />
+                <RagSourcesGroup />
+                <MessageHtmlArtifacts />
+              </>
+            )}
             <MessageError />
           </>
         )}

studio/frontend/src/components/markdown/markdown-preview.tsx

@@ -1,15 +1,33 @@
 // 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 { openLink } from "@/lib/open-link";
 import { cn } from "@/lib/utils";
 import { code } from "@streamdown/code";
 import { math } from "@streamdown/math";
 import { mermaid } from "@streamdown/mermaid";
-import { memo, type ReactElement } from "react";
+import { type ComponentProps, type ReactElement, memo } from "react";
 import { Streamdown } from "streamdown";
 import "katex/dist/katex.min.css";
 
 const MARKDOWN_PLUGINS = { code, math, mermaid } as const;
+const MARKDOWN_COMPONENTS = {
+  a: ({ href, children, ...props }: ComponentProps<"a">) => (
+    <a
+      href={href}
+      rel="noopener noreferrer"
+      className="cursor-pointer text-primary underline decoration-primary/40 underline-offset-2 transition-colors hover:decoration-primary"
+      onClick={(event) => {
+        if (href && openLink(href)) {
+          event.preventDefault();
+        }
+      }}
+      {...props}
+    >
+      {children}
+    </a>
+  ),
+};
 
 type MarkdownPreviewProps = {
   markdown: string;
@@ -37,6 +55,7 @@ function MarkdownPreviewImpl({
       <Streamdown
         mode="static"
         plugins={MARKDOWN_PLUGINS}
+        components={MARKDOWN_COMPONENTS}
         controls={false}
         className={markdownClassName}
       >

studio/frontend/src/features/auth/index.ts

@@ -5,6 +5,7 @@ export { LoginPage } from "./login-page";
 export { ChangePasswordPage } from "./change-password-page";
 export { authFetch, logout, refreshSession } from "./api";
 export {
+  AUTH_SESSION_CLEARED_EVENT,
   clearAuthTokens,
   getAuthToken,
   getPostAuthRoute,

studio/frontend/src/features/auth/session.ts

@@ -8,6 +8,7 @@ export const AUTH_TOKEN_KEY = "unsloth_auth_token";
 export const AUTH_REFRESH_TOKEN_KEY = "unsloth_auth_refresh_token";
 export const ONBOARDING_DONE_KEY = "unsloth_onboarding_done";
 export const AUTH_MUST_CHANGE_PASSWORD_KEY = "unsloth_auth_must_change_password";
+export const AUTH_SESSION_CLEARED_EVENT = "unsloth:auth-session-cleared";
 
 type PostAuthRoute = "/change-password" | "/chat";
 
@@ -52,6 +53,7 @@ export function clearAuthTokens(): void {
   localStorage.removeItem(AUTH_TOKEN_KEY);
   localStorage.removeItem(AUTH_REFRESH_TOKEN_KEY);
   localStorage.removeItem(AUTH_MUST_CHANGE_PASSWORD_KEY);
+  window.dispatchEvent(new Event(AUTH_SESSION_CLEARED_EVENT));
 }
 
 // Flag stored as key presence (constant "1" or absence), not a derived boolean,

studio/frontend/src/features/chat/api/chat-adapter.ts

@@ -71,6 +71,8 @@ import {
   getStoredChatThread,
   getStoredChatProject,
   listStoredChatThreads,
+  listStoredChatMessages,
+  saveStoredChatMessage,
   updateStoredChatThread,
 } from "../utils/chat-history-storage";
 import {
@@ -102,6 +104,16 @@ import {
   encryptProviderApiKey,
   isProviderKeyRotationError,
 } from "./providers-api";
+import {
+  beginExternalResearchFollow,
+  ingestResearchUpdate,
+  useResearchRunStore,
+} from "../stores/research-run-store";
+import {
+  cancelResearchRun,
+  createResearchRun,
+  followResearchRun,
+} from "./research-api";
 
 // Small models (<=9B) answer from memory instead of calling search, so "auto"
 // forces retrieval for them and leaves it to larger ones.
@@ -1915,13 +1927,229 @@ export function createOpenAIStreamAdapter(
   options: OpenAIStreamAdapterOptions = {},
 ): ChatModelAdapter {
   return {
-    async *run({ messages, abortSignal, unstable_threadId }) {
+    async *run({
+      messages,
+      abortSignal,
+      unstable_threadId,
+      unstable_assistantMessageId,
+    }) {
       await useChatRuntimeStore.getState().hydratePersistedSettings();
       let runtime = useChatRuntimeStore.getState();
       // Capture the thread ID once so it stays stable even if the user
       // switches chats while waiting for model load / auto-load.
       const resolvedThreadId =
         (unstable_threadId ?? runtime.activeThreadId) || undefined;
+      const threadAlreadyResearched = Boolean(
+        resolvedThreadId &&
+          useResearchRunStore.getState().claimedThreadIds[resolvedThreadId],
+      );
+      if (runtime.deepResearchEnabled && threadAlreadyResearched) {
+        runtime.setDeepResearchEnabled(false);
+        runtime = useChatRuntimeStore.getState();
+      }
+      if (
+        runtime.deepResearchEnabled &&
+        !options.pairId &&
+        (options.modelType === undefined || options.modelType === "base")
+      ) {
+        if (runtime.modelLoading) {
+          toast.info("Waiting for model to finish loading…");
+          await waitForModelReady(abortSignal);
+        }
+        if (!useChatRuntimeStore.getState().params.checkpoint) {
+          const { loaded, blockedByTrustRemoteCode } =
+            await autoLoadSmallestModel();
+          if (!loaded) {
+            toast.error(
+              blockedByTrustRemoteCode
+                ? "This model needs custom code approval"
+                : "No model loaded",
+              {
+                description: blockedByTrustRemoteCode
+                  ? "Select it from the top bar to review and approve its custom code, or pick another model."
+                  : "Pick a model in the top bar, then retry.",
+              },
+            );
+            throw new Error("Load a model first.");
+          }
+        }
+        runtime = useChatRuntimeStore.getState();
+        if (!resolvedThreadId) throw new Error("Research requires a saved chat.");
+        if (!unstable_assistantMessageId) {
+          throw new Error(
+            "Deep research could not bind its assistant message. Please retry the send.",
+          );
+        }
+        const userMessage = [...messages].reverse().find((m) => m.role === "user");
+        if (!userMessage) throw new Error("Research requires a user message.");
+        const { params } = runtime;
+        const model = params.checkpoint.trim();
+        if (!model || parseExternalModelId(model)) {
+          throw new Error("Deep research requires a selected local model.");
+        }
+        const inferenceRequest: {
+          model: string;
+          temperature?: number;
+          topP?: number;
+          maxTokens?: number;
+          enableThinking?: boolean;
+          reasoningEffort?: string;
+        } = { model };
+        if (
+          Number.isFinite(params.temperature) &&
+          params.temperature >= 0 &&
+          params.temperature <= 2
+        ) {
+          inferenceRequest.temperature = params.temperature;
+        }
+        if (Number.isFinite(params.topP) && params.topP > 0 && params.topP <= 1) {
+          inferenceRequest.topP = params.topP;
+        }
+        if (Number.isFinite(params.maxTokens) && params.maxTokens > 0) {
+          inferenceRequest.maxTokens = Math.min(8192, Math.floor(params.maxTokens));
+        }
+        const reasoningRequested =
+          runtime.reasoningAlwaysOn ||
+          (runtime.reasoningEnabled && runtime.reasoningEffort !== "none");
+        if (
+          runtime.reasoningStyle === "enable_thinking" ||
+          runtime.reasoningStyle === "enable_thinking_effort"
+        ) {
+          inferenceRequest.enableThinking = reasoningRequested;
+        }
+        if (
+          reasoningRequested &&
+          (runtime.reasoningStyle === "reasoning_effort" ||
+            runtime.reasoningStyle === "enable_thinking_effort")
+        ) {
+          inferenceRequest.reasoningEffort = runtime.reasoningEffort;
+        }
+        const researchProjectId = await resolveProjectId(resolvedThreadId);
+        const ragScope =
+          runtime.ragEnabled || researchProjectId
+            ? runtime.ragEnabled && runtime.ragSource.type === "kb"
+              ? {
+                  kb_id: runtime.ragSource.kbId,
+                   default_top_k: runtime.ragTopK,
+                   mode: runtime.ragMode,
+                   autoinject: runtime.ragAutoInject,
+                   autoinject_min_score: runtime.ragAutoInjectMinScore,
+                }
+              : {
+                  thread_id: resolvedThreadId,
+                  ...(researchProjectId
+                    ? { project_id: researchProjectId }
+                    : {}),
+                   default_top_k: runtime.ragTopK,
+                   mode: runtime.ragMode,
+                   autoinject: runtime.ragAutoInject,
+                   autoinject_min_score: runtime.ragAutoInjectMinScore,
+                }
+            : undefined;
+
+        const threadKey = resolvedThreadId;
+        runtime.setThreadRunning(threadKey, true);
+        let report = "";
+        let releaseResearchFollow: (() => void) | null = null;
+        const researchFollowController = new AbortController();
+        const detachResearchFollow = () => {
+          researchFollowController.abort({ detach: true });
+        };
+        const forwardAdapterAbort = () => {
+          researchFollowController.abort(abortSignal.reason);
+        };
+        abortSignal.addEventListener("abort", forwardAdapterAbort, { once: true });
+        try {
+          // The normal history adapter persists messages after model execution,
+          // but research validates the user message before it can start.
+          const storedUserMessage = (await listStoredChatMessages(resolvedThreadId)).find(
+            (message) => message.id === userMessage.id,
+          );
+          await saveStoredChatMessage({
+            id: userMessage.id,
+            threadId: resolvedThreadId,
+            parentId: storedUserMessage?.parentId ?? null,
+            role: "user",
+            content: userMessage.content,
+            ...(userMessage.attachments?.length
+              ? { attachments: userMessage.attachments }
+              : {}),
+            createdAt: userMessage.createdAt?.getTime?.() ?? Date.now(),
+          });
+          const createdRun = await createResearchRun({
+            threadId: resolvedThreadId,
+            userMessageId: userMessage.id,
+            assistantMessageId: unstable_assistantMessageId,
+            inferenceRequest,
+            ...(ragScope ? { ragScope } : {}),
+            websitePolicy: {
+              allowedDomains: [...runtime.researchWebsitePolicy.allowedDomains],
+              blockedDomains: [...runtime.researchWebsitePolicy.blockedDomains],
+            },
+          });
+          releaseResearchFollow = beginExternalResearchFollow(
+            createdRun,
+            detachResearchFollow,
+          );
+          runtime.setDeepResearchEnabled(false);
+          if (abortSignal.aborted) {
+            const detached = Boolean(
+              (abortSignal.reason as { detach?: boolean } | undefined)?.detach,
+            );
+            if (!detached) {
+              try {
+                ingestResearchUpdate(await cancelResearchRun(createdRun.id));
+              } catch {
+                // The durable run remains visible and can be stopped again after recovery.
+              }
+            }
+            return;
+          }
+          for await (const update of followResearchRun(createdRun.id, {
+            initialRun: createdRun,
+            signal: researchFollowController.signal,
+            replayFrom: 0,
+          })) {
+            const run = update.run;
+            ingestResearchUpdate(run, update.event);
+            // The activity store coalesces these high-frequency events. Yielding
+            // them through assistant-ui would replace the entire hidden message
+            // content for every token and make long planning turns progressively
+            // more expensive.
+            if (
+              update.event?.event === "reasoning.updated" ||
+              update.event?.event === "report.updated"
+            ) {
+              continue;
+            }
+            if (run.status === "completed" && typeof run.report === "string") {
+              report = run.report;
+            } else if (typeof run.report === "string") {
+              report = run.report;
+            }
+            yield {
+              content: [{ type: "text" as const, text: report }],
+              metadata: {
+                custom: {
+                  researchRunId: run.id,
+                  researchRun: run,
+                  serverManaged: true,
+                  serverRevision: run.lastEventSeq,
+                },
+              },
+            };
+          }
+        } catch (error) {
+          if (!abortSignal.aborted && !researchFollowController.signal.aborted) {
+            throw error;
+          }
+        } finally {
+          abortSignal.removeEventListener("abort", forwardAdapterAbort);
+          releaseResearchFollow?.();
+          runtime.setThreadRunning(threadKey, false);
+        }
+        return;
+      }
       const sandboxSessionId = await resolveSandboxSessionId(resolvedThreadId);
       const toolConfirmationScopeId = resolvedThreadId
         ? `${sandboxSessionId || "_default"}:${resolvedThreadId}`

studio/frontend/src/features/chat/api/research-api.ts

@@ -0,0 +1,341 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { authFetch } from "@/features/auth";
+import type {
+  CreateResearchRunInput,
+  ResearchEvent,
+  ResearchPlan,
+  ResearchRun,
+} from "../types/research";
+
+type JsonObject = Record<string, unknown>;
+const TERMINAL_RESEARCH_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+class ResearchApiError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "ResearchApiError";
+    this.status = status;
+  }
+}
+
+function camelize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(camelize);
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value as JsonObject).map(([key, child]) => [
+      key.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase()),
+      camelize(child),
+    ]),
+  );
+}
+
+async function json<T>(response: Response): Promise<T> {
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    const detail = (body as { detail?: unknown; message?: unknown } | null)
+      ?.detail;
+    const message = (body as { message?: unknown } | null)?.message;
+    throw new ResearchApiError(
+      typeof detail === "string"
+        ? detail
+        : typeof message === "string"
+          ? message
+          : `Research request failed (${response.status})`,
+      response.status,
+    );
+  }
+  return camelize(body) as T;
+}
+
+export async function createResearchRun(
+  input: CreateResearchRunInput,
+): Promise<ResearchRun> {
+  return json<ResearchRun>(
+    await authFetch("/api/chat/research-runs", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+  );
+}
+
+export async function getResearchRun(
+  id: string,
+  signal?: AbortSignal,
+): Promise<ResearchRun> {
+  return json<ResearchRun>(
+    await authFetch(`/api/chat/research-runs/${id}`, { signal }),
+  );
+}
+
+export async function getResearchThreadState(
+  threadId: string,
+): Promise<{ activeRun: ResearchRun | null; hasRun: boolean }> {
+  const query = new URLSearchParams({ threadId });
+  const response = await authFetch(`/api/chat/research-runs/active?${query}`);
+  if (response.status === 404) {
+    return { activeRun: null, hasRun: false };
+  }
+  const { runs, hasRun } = await json<{
+    runs: ResearchRun[];
+    hasRun: boolean;
+  }>(response);
+  return { activeRun: runs.at(-1) ?? null, hasRun };
+}
+
+async function mutate(
+  id: string,
+  action: string,
+  body?: Record<string, unknown>,
+): Promise<ResearchRun> {
+  return json<ResearchRun>(
+    await authFetch(`/api/chat/research-runs/${id}/${action}`, {
+      method: "POST",
+      ...(body
+        ? {
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+          }
+        : {}),
+    }),
+  );
+}
+
+export const approveResearchRun = (
+  id: string,
+  planRevision: number,
+  planHash: string,
+) => mutate(id, "approve", { planRevision, planHash });
+export const cancelResearchRun = (id: string) => mutate(id, "cancel");
+export const retryResearchRun = (id: string) => mutate(id, "retry");
+
+export async function updateResearchPlan(
+  id: string,
+  plan: ResearchPlan,
+  expectedRevision: number,
+): Promise<ResearchRun> {
+  return json<ResearchRun>(
+    await authFetch(`/api/chat/research-runs/${id}/plan`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ plan, expectedRevision }),
+    }),
+  );
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Incremental SSE parsing must retain framing state across reader chunks.
+export async function* streamResearchEvents(
+  id: string,
+  after: number,
+  signal?: AbortSignal,
+): AsyncGenerator<ResearchEvent> {
+  const response = await authFetch(
+    `/api/chat/research-runs/${id}/events?after=${Math.max(0, after)}`,
+    { headers: { accept: "text/event-stream" }, signal },
+  );
+  if (!response.ok) {
+    await json(response);
+  }
+  if (!response.body) {
+    throw new Error("Research event stream returned no response body");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done }).replace(/\r\n/g, "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary >= 0) {
+        const block = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        let event = "message";
+        let eventId = after;
+        const data: string[] = [];
+        for (const line of block.split("\n")) {
+          if (line.startsWith("id:")) {
+            eventId = Number(line.slice(3).trim()) || eventId;
+          } else if (line.startsWith("event:")) {
+            event = line.slice(6).trim();
+          } else if (line.startsWith("data:")) {
+            data.push(line.slice(5).trimStart());
+          }
+        }
+        if (data.length > 0) {
+          const parsed = camelize(JSON.parse(data.join("\n"))) as JsonObject;
+          const candidate = parsed.run as ResearchRun | undefined;
+          if (candidate?.id && candidate.status) {
+            yield {
+              id: eventId,
+              event: event as ResearchEvent["event"],
+              createdAt:
+                typeof parsed.createdAt === "number"
+                  ? parsed.createdAt
+                  : candidate.updatedAt,
+              data: parsed as unknown as ResearchEvent["data"],
+              run: candidate,
+            };
+          }
+        }
+        boundary = buffer.indexOf("\n\n");
+      }
+      if (done) {
+        return;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+export interface ResearchRunUpdate {
+  run: ResearchRun;
+  event?: ResearchEvent;
+  source: "snapshot" | "event";
+}
+
+function isPermanentResearchError(error: unknown): boolean {
+  return (
+    error instanceof ResearchApiError &&
+    error.status >= 400 &&
+    error.status < 500 &&
+    error.status !== 408 &&
+    error.status !== 429
+  );
+}
+
+function waitForReconnect(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const finish = () => {
+      window.clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    };
+    const timer = window.setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+
+/** Follow a durable run across clean SSE EOFs and transient network failures. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: The retry, cursor, abort, and terminal states belong to one reconnect state machine.
+export async function* followResearchRun(
+  id: string,
+  options: {
+    initialRun?: ResearchRun;
+    signal?: AbortSignal;
+    replayFrom?: number;
+  } = {},
+): AsyncGenerator<ResearchRunUpdate> {
+  const { signal, replayFrom } = options;
+  let run = options.initialRun;
+  let failures = 0;
+  while (!(run || signal?.aborted)) {
+    try {
+      run = await getResearchRun(id, signal);
+    } catch (error) {
+      if (signal?.aborted) {
+        return;
+      }
+      if (isPermanentResearchError(error)) {
+        throw error;
+      }
+      failures += 1;
+      await waitForReconnect(
+        Math.min(8_000, 500 * 2 ** (failures - 1)),
+        signal,
+      );
+    }
+  }
+  if (!run || signal?.aborted) {
+    return;
+  }
+  failures = 0;
+  yield { run, source: "snapshot" };
+  if (
+    (TERMINAL_RESEARCH_STATUSES.has(run.status) && replayFrom === undefined) ||
+    signal?.aborted
+  ) {
+    return;
+  }
+  let cursor = replayFrom ?? run.lastEventSeq;
+  while (!signal?.aborted) {
+    try {
+      for await (const event of streamResearchEvents(id, cursor, signal)) {
+        cursor = Math.max(cursor, event.id);
+        run = event.run;
+        failures = 0;
+        yield { run, event, source: "event" };
+        if (
+          (event.event === "run.completed" ||
+            event.event === "run.failed" ||
+            event.event === "run.cancelled") &&
+          TERMINAL_RESEARCH_STATUSES.has(event.run.status) &&
+          (event.data.attempt ?? 0) === (event.run.retryCount ?? 0)
+        ) {
+          return;
+        }
+      }
+    } catch (error) {
+      if (signal?.aborted) {
+        return;
+      }
+      if (isPermanentResearchError(error)) {
+        throw error;
+      }
+      failures += 1;
+    }
+
+    if (signal?.aborted) {
+      return;
+    }
+    try {
+      const fresh = await getResearchRun(id, signal);
+      const changed =
+        fresh.lastEventSeq !== run.lastEventSeq ||
+        fresh.updatedAt !== run.updatedAt ||
+        fresh.status !== run.status ||
+        fresh.report !== run.report;
+      const needsCatchup = cursor < fresh.lastEventSeq;
+      run = fresh;
+      if (replayFrom === undefined) {
+        cursor = Math.max(cursor, fresh.lastEventSeq);
+      }
+      if (changed || needsCatchup) {
+        yield { run, source: "snapshot" };
+      }
+      if (
+        TERMINAL_RESEARCH_STATUSES.has(run.status) &&
+        cursor >= run.lastEventSeq
+      ) {
+        return;
+      }
+    } catch (error) {
+      if (signal?.aborted) {
+        return;
+      }
+      if (isPermanentResearchError(error)) {
+        throw error;
+      }
+      failures += 1;
+    }
+    await waitForReconnect(
+      Math.min(8_000, 500 * 2 ** Math.max(0, failures - 1)),
+      signal,
+    );
+  }
+}

studio/frontend/src/features/chat/chat-page.tsx

@@ -28,6 +28,7 @@ import {
 import { useSidebar } from "@/components/ui/sidebar";
 import { Tooltip, TooltipContent } from "@/components/ui/tooltip";
 import { useLatestRef } from "@/features/hub/hooks/use-latest-ref";
+import { useIsMobile } from "@/hooks/use-mobile";
 import {
   DOWNLOAD_KIND,
   downloadManager,
@@ -55,6 +56,7 @@ import {
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useNavigate } from "@tanstack/react-router";
 import { Tooltip as TooltipPrimitive } from "radix-ui";
+import { Telescope } from "lucide-react";
 import {
   type CSSProperties,
   type ReactElement,
@@ -77,6 +79,10 @@ import {
 } from "./artifacts/store";
 import type { ChatArtifact, ChatArtifactSurface } from "./artifacts/types";
 import { ChatSettingsPanel } from "./chat-settings-sheet";
+import {
+  ResearchActivityPanel,
+  ResearchActivitySheet,
+} from "./components/research-activity-panel";
 import { ContextUsageBar } from "./components/context-usage-bar";
 import { ModelLoadInlineStatus } from "./components/model-load-status";
 import { ProjectSwitcher } from "./components/project-switcher";
@@ -133,6 +139,7 @@ import {
 } from "./stores/chat-runtime-store";
 import type { PendingModelSelection } from "./stores/chat-runtime-store";
 import { useChatPreferencesStore } from "./stores/chat-preferences-store";
+import { useResearchRunStore } from "./stores/research-run-store";
 import { useExternalProvidersStore } from "./stores/external-providers-store";
 import { buildChatTourSteps } from "./tour";
 import type { ChatView, MessageRecord } from "./types";
@@ -239,6 +246,19 @@ const SingleContent = memo(function SingleContent({
 }): ReactElement {
   const openArtifact = useChatArtifactsStore((state) => state.openArtifact);
   const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const isMobile = useIsMobile();
+  const chatActive = useChatActive();
+  const openResearchRunId = useResearchRunStore((state) => state.openRunId);
+  const closeResearchPanel = useResearchRunStore((state) => state.closePanel);
+  useEffect(() => {
+    if (!activeThreadId || !openResearchRunId) return;
+    const openRun =
+      useResearchRunStore.getState().sessions[openResearchRunId]?.run;
+    if (openRun && openRun.threadId !== activeThreadId) closeResearchPanel();
+  }, [activeThreadId, openResearchRunId, closeResearchPanel]);
+  const openResearchRun = useResearchRunStore((state) =>
+    openResearchRunId ? state.sessions[openResearchRunId]?.run : undefined,
+  );
   const artifactPanelRef = useRef<PanelImperativeHandle | null>(null);
   const hasInitializedArtifactPanelRef = useRef(false);
   const [isArtifactLayoutAnimating, setIsArtifactLayoutAnimating] =
@@ -247,7 +267,12 @@ const SingleContent = memo(function SingleContent({
     useState(false);
   const [isArtifactSurfaceVisible, setIsArtifactSurfaceVisible] =
     useState(false);
-  const showArtifactPanel = Boolean(
+  const researchMatchesThread = Boolean(
+    openResearchRun &&
+      openResearchRun.threadId === (threadId ?? activeThreadId),
+  );
+  const showResearchPanel = researchMatchesThread && !isMobile;
+  const showArtifactPanel = !showResearchPanel && Boolean(
     artifact &&
       artifactSurface === "panel" &&
       (threadId
@@ -255,10 +280,11 @@ const SingleContent = memo(function SingleContent({
         : Boolean(newThreadNonce) ||
           Boolean(artifact.threadId && artifact.threadId === activeThreadId)),
   );
+  const showContextPanel = showResearchPanel || showArtifactPanel;
 
-  const artifactLayoutActive = showArtifactPanel || isArtifactPanelLayoutActive;
+  const artifactLayoutActive = showContextPanel || isArtifactPanelLayoutActive;
   const artifactPanelSettledOpen =
-    showArtifactPanel &&
+    showContextPanel &&
     isArtifactPanelLayoutActive &&
     !isArtifactLayoutAnimating;
 
@@ -270,7 +296,7 @@ const SingleContent = memo(function SingleContent({
 
     if (!hasInitializedArtifactPanelRef.current) {
       hasInitializedArtifactPanelRef.current = true;
-      if (!showArtifactPanel) {
+       if (!showContextPanel) {
         panel.resize("0%");
         return;
       }
@@ -281,17 +307,17 @@ const SingleContent = memo(function SingleContent({
     let resizeFrameId = 0;
     const prepFrameId = window.requestAnimationFrame(() => {
       resizeFrameId = window.requestAnimationFrame(() => {
-        panel.resize(showArtifactPanel ? ARTIFACT_PANEL_DEFAULT_SIZE : "0%");
+        panel.resize(showContextPanel ? ARTIFACT_PANEL_DEFAULT_SIZE : "0%");
       });
     });
-    const surfaceTimerId = showArtifactPanel
+    const surfaceTimerId = showContextPanel
       ? window.setTimeout(() => {
           setIsArtifactSurfaceVisible(true);
         }, ARTIFACT_SURFACE_POP_DELAY_MS)
       : 0;
     const timeoutId = window.setTimeout(() => {
       setIsArtifactLayoutAnimating(false);
-      if (!showArtifactPanel) {
+      if (!showContextPanel) {
         setIsArtifactPanelLayoutActive(false);
       }
     }, ARTIFACT_PANEL_TRANSITION_MS + 60);
@@ -305,7 +331,13 @@ const SingleContent = memo(function SingleContent({
       }
       window.clearTimeout(timeoutId);
     };
-  }, [showArtifactPanel]);
+  }, [showContextPanel]);
+
+  useEffect(() => {
+    if (!researchMatchesThread) return;
+    onCloseArtifact();
+    useChatRuntimeStore.getState().setSettingsPanelOpen(false);
+  }, [researchMatchesThread, onCloseArtifact]);
 
   const threadPane = (
     <div className="flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
@@ -342,29 +374,51 @@ const SingleContent = memo(function SingleContent({
           withHandle={false}
           className={cn(
             "relative z-30 -ml-1 -mr-4 w-5 bg-transparent transition-[width,margin] duration-[260ms] ease-[var(--ease-out-cubic)] hover:bg-transparent hover:shadow-none active:bg-transparent active:shadow-none focus-visible:bg-transparent focus-visible:shadow-none focus-visible:ring-0 focus-visible:ring-offset-0 focus-visible:outline-none",
-            !artifactLayoutActive && "pointer-events-none -ml-0 -mr-0 w-0",
+            !artifactLayoutActive &&
+              "pointer-events-none -ml-0 -mr-0 w-0",
           )}
         />
         <ResizablePanel
           panelRef={artifactPanelRef}
           id="chat-artifact"
           defaultSize="0%"
-          minSize={artifactPanelSettledOpen ? "30%" : "0%"}
-          maxSize={artifactLayoutActive ? "58%" : "0%"}
-          collapsible={true}
+          minSize={
+            showResearchPanel
+              ? "30%"
+              : artifactPanelSettledOpen
+                ? "30%"
+                : "0%"
+          }
+          maxSize={
+            showResearchPanel
+              ? "58%"
+              : artifactLayoutActive
+                ? "58%"
+                : "0%"
+          }
+          collapsible={showArtifactPanel}
           collapsedSize="0%"
           className={cn(
             "h-full min-h-0 min-w-0 overflow-visible",
-            !showArtifactPanel && "pointer-events-none",
+            !showContextPanel && "pointer-events-none",
           )}
         >
           <div
             data-artifact-surface-visible={
               isArtifactSurfaceVisible ? "true" : "false"
             }
-            className="chat-artifact-pop-surface flex h-full min-h-0 min-w-0 flex-col overflow-visible"
+            className={cn(
+              "chat-artifact-pop-surface flex h-full min-h-0 min-w-0 flex-col overflow-visible",
+              showResearchPanel && "border-l border-border/70",
+            )}
           >
-            {showArtifactPanel && artifact ? (
+             {showResearchPanel && openResearchRunId ? (
+               <ResearchActivityPanel
+                 key={openResearchRunId}
+                 runId={openResearchRunId}
+                 onClose={closeResearchPanel}
+               />
+             ) : showArtifactPanel && artifact ? (
               <ArtifactSurface
                 artifact={artifact}
                 variant="panel"
@@ -377,6 +431,15 @@ const SingleContent = memo(function SingleContent({
           </div>
         </ResizablePanel>
       </ResizablePanelGroup>
+      {openResearchRunId && researchMatchesThread ? (
+        <ResearchActivitySheet
+          runId={openResearchRunId}
+          open={chatActive && isMobile}
+          onOpenChange={(open) => {
+            if (!open) closeResearchPanel();
+          }}
+        />
+      ) : null}
     </ChatRuntimeProvider>
   );
 });
@@ -1371,6 +1434,15 @@ export function ChatPage({
   const clearCheckpoint = useChatRuntimeStore((state) => state.clearCheckpoint);
   const resetArtifacts = useChatArtifactsStore((state) => state.resetArtifacts);
   const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const latestResearchRunId = useResearchRunStore((state) =>
+    activeThreadId ? state.latestRunByThreadId[activeThreadId] : undefined,
+  );
+  const latestResearchRun = useResearchRunStore((state) =>
+    latestResearchRunId ? state.sessions[latestResearchRunId]?.run : undefined,
+  );
+  const openResearchPanel = useResearchRunStore((state) => state.openPanel);
+  const openResearchRunId = useResearchRunStore((state) => state.openRunId);
+  const closeResearchPanel = useResearchRunStore((state) => state.closePanel);
   const [currentProjectId, setCurrentProjectId] = useState<string | null>(
     search.project ?? null,
   );
@@ -2711,12 +2783,44 @@ export function ChatPage({
                 </TooltipContent>
               </Tooltip>
             )}
+            {view.mode === "single" && latestResearchRun ? (
+              <Tooltip>
+                <TooltipPrimitive.Trigger asChild={true}>
+                  <button
+                    type="button"
+                    onClick={() => {
+                      if (openResearchRunId === latestResearchRun.id) {
+                        closeResearchPanel();
+                        return;
+                      }
+                      setSettingsOpen(false);
+                      closeArtifactSurface();
+                      openResearchPanel(latestResearchRun.id);
+                    }}
+                    className="relative flex size-[var(--studio-chat-control-height,34px)] cursor-pointer items-center justify-center rounded-[12px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring dark:hover:text-white"
+                    aria-label="Open research activity"
+                    aria-pressed={openResearchRunId === latestResearchRun.id}
+                  >
+                    <Telescope className="size-icon" strokeWidth={1.75} />
+                    {!['completed', 'failed', 'cancelled'].includes(latestResearchRun.status) ? (
+                      <span className="absolute right-1 top-1 size-1.5 rounded-full bg-primary ring-2 ring-background" />
+                    ) : null}
+                  </button>
+                </TooltipPrimitive.Trigger>
+                <TooltipContent side="bottom" sideOffset={6} className="tooltip-compact">
+                  Research activity
+                </TooltipContent>
+              </Tooltip>
+            ) : null}
             {!settingsOpen && (
               <Tooltip>
                 <TooltipPrimitive.Trigger asChild={true}>
                   <button
                     type="button"
-                    onClick={() => setSettingsOpen(true)}
+                    onClick={() => {
+                      useResearchRunStore.getState().closePanel();
+                      setSettingsOpen(true);
+                    }}
                     className="flex size-[var(--studio-chat-control-height,34px)] translate-x-[2px] cursor-pointer items-center justify-center rounded-[12px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
                     aria-label="Open run settings"
                   >

studio/frontend/src/features/chat/components/deep-research-composer-button.tsx

@@ -0,0 +1,243 @@
+// 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 { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { ChevronDownIcon, GlobeLockIcon, TelescopeIcon, XIcon } from "lucide-react";
+import { type KeyboardEvent, useState } from "react";
+import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+import type { ResearchWebsitePolicy } from "../types/research";
+
+function normalizeDomain(raw: string): string | null {
+  const value = raw.trim();
+  if (!value || /[\\\s]/.test(value)) return null;
+  try {
+    const url = new URL(value.includes("://") ? value : `https://${value}`);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.port) {
+      return null;
+    }
+    return url.hostname
+      .toLowerCase()
+      .replace(/^\[|\]$/g, "")
+      .replace(/\.$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function DomainList({
+  label,
+  description,
+  values,
+  onChange,
+}: {
+  label: string;
+  description: string;
+  values: string[];
+  onChange: (values: string[]) => void;
+}) {
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState("");
+
+  const addDraft = () => {
+    if (!draft.trim()) return;
+    const domain = normalizeDomain(draft);
+    if (!domain) {
+      setError("Enter a domain without a port, such as arxiv.org.");
+      return;
+    }
+    if (values.length >= 100 && !values.includes(domain)) {
+      setError("You can add up to 100 domains to each list.");
+      return;
+    }
+    if (!values.includes(domain)) onChange([...values, domain]);
+    setDraft("");
+    setError("");
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "Enter" || event.key === ",") {
+      event.preventDefault();
+      addDraft();
+    } else if (event.key === "Backspace" && !draft && values.length) {
+      onChange(values.slice(0, -1));
+    }
+  };
+
+  return (
+    <div className="space-y-2">
+      <div>
+        <div className="text-sm font-medium">{label}</div>
+        <p className="mt-0.5 text-xs leading-relaxed text-muted-foreground">
+          {description}
+        </p>
+      </div>
+      <div
+        className={cn(
+          "flex min-h-10 flex-wrap items-center gap-1.5 rounded-2xl border border-input bg-input/20 p-1.5 transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
+          error && "border-destructive/70",
+        )}
+      >
+        {values.map((domain) => (
+          <span
+            key={domain}
+            className="flex h-6 items-center gap-1 rounded-full bg-muted px-2 text-xs font-medium"
+          >
+            {domain}
+            <button
+              type="button"
+              className="text-muted-foreground transition-colors hover:text-foreground"
+              aria-label={`Remove ${domain}`}
+              onClick={() => onChange(values.filter((value) => value !== domain))}
+            >
+              <XIcon className="size-3" />
+            </button>
+          </span>
+        ))}
+        <Input
+          value={draft}
+          onChange={(event) => {
+            setDraft(event.target.value);
+            setError("");
+          }}
+          onBlur={addDraft}
+          onKeyDown={handleKeyDown}
+          placeholder={values.length ? "Add another domain" : "example.com"}
+          aria-invalid={Boolean(error)}
+          className="h-7 min-w-36 flex-1 border-0 bg-transparent px-1 shadow-none focus-visible:ring-0"
+        />
+      </div>
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+    </div>
+  );
+}
+
+export function DeepResearchComposerButton({
+  onConfigure,
+}: {
+  onConfigure: () => void;
+}) {
+  const enabled = useChatRuntimeStore((state) => state.deepResearchEnabled);
+  const setEnabled = useChatRuntimeStore((state) => state.setDeepResearchEnabled);
+  const policy = useChatRuntimeStore((state) => state.researchWebsitePolicy);
+
+  if (!enabled) return null;
+  const limited = policy.allowedDomains.length + policy.blockedDomains.length > 0;
+
+  return (
+    <button
+      type="button"
+      onClick={onConfigure}
+      className="composer-pill-btn"
+      data-pill-label="Deep research"
+      data-active="true"
+      aria-label="Configure Deep Research website access"
+      title="Configure website access"
+    >
+      <span
+        role="button"
+        aria-label="Disable deep research"
+        tabIndex={-1}
+        onPointerDown={(event) => event.stopPropagation()}
+        onClick={(event) => {
+          event.stopPropagation();
+          setEnabled(false);
+        }}
+        className="composer-pill-glyph cursor-pointer"
+      >
+        <TelescopeIcon className="size-[15px]" />
+        <XIcon className="composer-pill-x" />
+      </span>
+      <span>Deep research</span>
+      <span className="composer-pill-caret flex items-center gap-0.5 text-primary/70">
+        <GlobeLockIcon className={cn("size-3.5", !limited && "opacity-55")} />
+        <span className="text-[11px] font-medium">Websites</span>
+        <ChevronDownIcon className="size-3" />
+      </span>
+    </button>
+  );
+}
+
+export function DeepResearchWebsiteAccessDialog({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const policy = useChatRuntimeStore((state) => state.researchWebsitePolicy);
+  const setPolicy = useChatRuntimeStore((state) => state.setResearchWebsitePolicy);
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      {open ? (
+        <DeepResearchWebsiteAccessContent
+          policy={policy}
+          setPolicy={setPolicy}
+          onClose={() => onOpenChange(false)}
+        />
+      ) : null}
+    </Dialog>
+  );
+}
+
+function DeepResearchWebsiteAccessContent({
+  policy,
+  setPolicy,
+  onClose,
+}: {
+  policy: ResearchWebsitePolicy;
+  setPolicy: (policy: ResearchWebsitePolicy) => void;
+  onClose: () => void;
+}) {
+  const [draft, setDraft] = useState<ResearchWebsitePolicy>(policy);
+
+  return (
+    <DialogContent className="sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>Website access</DialogTitle>
+          <DialogDescription>
+            Control which websites the next Deep Research run can search and
+            read. Limits are enforced by the server and shared with the research
+            model.
+          </DialogDescription>
+        </DialogHeader>
+        <div className="space-y-6">
+          <DomainList
+            label="Allow only"
+            description="When set, research can access only these domains and their subdomains."
+            values={draft.allowedDomains}
+            onChange={(allowedDomains) => setDraft({ ...draft, allowedDomains })}
+          />
+          <DomainList
+            label="Always block"
+            description="These domains and their subdomains stay blocked. Blocking takes precedence."
+            values={draft.blockedDomains}
+            onChange={(blockedDomains) => setDraft({ ...draft, blockedDomains })}
+          />
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button
+            onClick={() => {
+              setPolicy(draft);
+              onClose();
+            }}
+          >
+            Save limits
+          </Button>
+        </DialogFooter>
+    </DialogContent>
+  );
+}

studio/frontend/src/features/chat/components/research-activity-panel.tsx

@@ -0,0 +1,972 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet";
+import { Spinner } from "@/components/ui/spinner";
+import { Textarea } from "@/components/ui/textarea";
+import { openLink } from "@/lib/open-link";
+import { toast } from "@/lib/toast";
+import { cn } from "@/lib/utils";
+import {
+  ArrowDown,
+  ArrowUp,
+  BookOpen,
+  Brain,
+  Check,
+  ChevronDown,
+  ExternalLink,
+  FileText,
+  Globe2,
+  Pencil,
+  Plus,
+  RotateCcw,
+  Search,
+  Square,
+  Telescope,
+  Trash2,
+  X,
+} from "lucide-react";
+import {
+  useCallback,
+  type ReactElement,
+  memo,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { motion, useReducedMotion } from "motion/react";
+import {
+  approveResearchRun,
+  retryResearchRun,
+  updateResearchPlan,
+} from "../api/research-api";
+import {
+  type ResearchActivity,
+  ensureResearchRunFollowed,
+  ingestResearchUpdate,
+  isSettledResearchRun,
+  useResearchRunStore,
+} from "../stores/research-run-store";
+import type { ResearchRunStatus } from "../types/research";
+
+const terminalStatuses = new Set<ResearchRunStatus>([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+const ACTIVITY_FOLLOW_SETTLE_MS = 450;
+const ACTIVITY_BOTTOM_THRESHOLD_PX = 24;
+
+function useResearchActivityScroll(runId: string) {
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const scrollToLatestRef = useRef<() => void>(() => undefined);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+
+  useLayoutEffect(() => {
+    const element = viewportRef.current;
+    if (!element) return;
+
+    let detached = false;
+    let pointerActive = false;
+    let touchStartY = 0;
+    let lastScrollTop = element.scrollTop;
+    let followUntil = performance.now() + ACTIVITY_FOLLOW_SETTLE_MS;
+    let animationFrame: number | null = null;
+
+    const distanceFromBottom = () =>
+      Math.max(
+        0,
+        element.scrollHeight - element.scrollTop - element.clientHeight,
+      );
+    const updateAtBottom = (value: boolean) =>
+      setIsAtBottom((current) => (current === value ? current : value));
+    const requestTick = () => {
+      if (animationFrame === null) animationFrame = requestAnimationFrame(tick);
+    };
+    const tick = () => {
+      animationFrame = null;
+      if (!detached && performance.now() < followUntil) {
+        if (distanceFromBottom() > 1) element.scrollTop = element.scrollHeight;
+        updateAtBottom(true);
+        requestTick();
+        return;
+      }
+      updateAtBottom(distanceFromBottom() <= ACTIVITY_BOTTOM_THRESHOLD_PX);
+    };
+    const followLayout = () => {
+      if (detached) return;
+      followUntil = performance.now() + ACTIVITY_FOLLOW_SETTLE_MS;
+      requestTick();
+    };
+    const detach = () => {
+      detached = true;
+      followUntil = 0;
+      updateAtBottom(false);
+    };
+    const innerScrollWillConsumeUpward = (target: EventTarget | null) => {
+      let node = target instanceof Element ? target : null;
+      while (node && node !== element) {
+        if (node.scrollTop > 0) {
+          const overflowY = window.getComputedStyle(node).overflowY;
+          if (overflowY === "auto" || overflowY === "scroll") return true;
+        }
+        node = node.parentElement;
+      }
+      return false;
+    };
+    const scrollToLatest = () => {
+      detached = false;
+      followUntil = performance.now() + ACTIVITY_FOLLOW_SETTLE_MS;
+      element.scrollTop = element.scrollHeight;
+      lastScrollTop = element.scrollTop;
+      updateAtBottom(true);
+      requestTick();
+    };
+    scrollToLatestRef.current = scrollToLatest;
+
+    const onScroll = () => {
+      const scrollTop = element.scrollTop;
+      const movingUp = scrollTop < lastScrollTop;
+      if (!detached && pointerActive && movingUp) detach();
+      if (
+        detached &&
+        scrollTop > lastScrollTop &&
+        distanceFromBottom() <= ACTIVITY_BOTTOM_THRESHOLD_PX
+      ) {
+        detached = false;
+        followLayout();
+      }
+      lastScrollTop = scrollTop;
+      if (detached) updateAtBottom(false);
+    };
+    const onWheel = (event: WheelEvent) => {
+      if (
+        event.deltaY < 0 &&
+        element.scrollTop > 0 &&
+        !innerScrollWillConsumeUpward(event.target)
+      ) {
+        detach();
+      }
+    };
+    const onTouchStart = (event: TouchEvent) => {
+      touchStartY = event.touches[0]?.clientY ?? 0;
+    };
+    const onTouchMove = (event: TouchEvent) => {
+      const y = event.touches[0]?.clientY ?? 0;
+      if (
+        y - touchStartY > 4 &&
+        element.scrollTop > 0 &&
+        !innerScrollWillConsumeUpward(event.target)
+      ) {
+        detach();
+      }
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (["ArrowUp", "PageUp", "Home"].includes(event.key)) detach();
+    };
+    const onPointerDown = () => {
+      pointerActive = true;
+    };
+    const onPointerUp = () => {
+      pointerActive = false;
+    };
+
+    const resizeObserver = new ResizeObserver(followLayout);
+    const mutationObserver = new MutationObserver(followLayout);
+    resizeObserver.observe(element, { box: "border-box" });
+    mutationObserver.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["data-state", "hidden", "aria-hidden"],
+    });
+    element.addEventListener("scroll", onScroll, { passive: true });
+    element.addEventListener("wheel", onWheel, { passive: true });
+    element.addEventListener("touchstart", onTouchStart, { passive: true });
+    element.addEventListener("touchmove", onTouchMove, { passive: true });
+    element.addEventListener("keydown", onKeyDown);
+    element.addEventListener("pointerdown", onPointerDown);
+    window.addEventListener("pointerup", onPointerUp);
+
+    scrollToLatest();
+
+    return () => {
+      if (animationFrame !== null) cancelAnimationFrame(animationFrame);
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      element.removeEventListener("scroll", onScroll);
+      element.removeEventListener("wheel", onWheel);
+      element.removeEventListener("touchstart", onTouchStart);
+      element.removeEventListener("touchmove", onTouchMove);
+      element.removeEventListener("keydown", onKeyDown);
+      element.removeEventListener("pointerdown", onPointerDown);
+      window.removeEventListener("pointerup", onPointerUp);
+      scrollToLatestRef.current = () => undefined;
+    };
+  }, [runId]);
+
+  const scrollToLatest = useCallback(() => scrollToLatestRef.current(), []);
+  return { viewportRef, isAtBottom, scrollToLatest };
+}
+
+export function researchStatusLabel(status: ResearchRunStatus): string {
+  switch (status) {
+    case "planning":
+      return "Planning";
+    case "awaiting_approval":
+      return "Review plan";
+    case "queued":
+      return "Queued";
+    case "running":
+      return "Researching";
+    case "paused":
+      return "Paused";
+    case "cancelling":
+      return "Stopping";
+    case "cancelled":
+      return "Cancelled";
+    case "completed":
+      return "Complete";
+    case "failed":
+      return "Failed";
+  }
+}
+
+function formatElapsed(start: number, end = Date.now()): string {
+  const seconds = Math.max(0, Math.round((end - start) / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return remainder ? `${minutes}m ${remainder}s` : `${minutes}m`;
+}
+
+function ActivityIcon({
+  activity,
+}: { activity: ResearchActivity }): ReactElement {
+  const className = "size-3.5";
+  if (activity.state === "running") return <Spinner className={className} />;
+  if (activity.state === "failed")
+    return <X className={cn(className, "text-destructive")} />;
+  if (activity.state === "cancelled")
+    return <Square className={cn(className, "text-muted-foreground")} />;
+  if (activity.kind === "reasoning") return <Brain className={className} />;
+  if (activity.kind === "plan") return <FileText className={className} />;
+  if (activity.kind === "report") return <FileText className={className} />;
+  if (activity.action === "fetch") return <BookOpen className={className} />;
+  if (activity.action === "search") return <Search className={className} />;
+  return <Check className={className} />;
+}
+
+const ActivityRow = memo(function ActivityRow({
+  runId,
+  activity,
+}: {
+  runId: string;
+  activity: ResearchActivity;
+}): ReactElement {
+  const storedOpen = useResearchRunStore(
+    (state) => state.activityOpenByRunId[runId]?.[activity.id],
+  );
+  const setActivityOpen = useResearchRunStore(
+    (state) => state.setActivityOpen,
+  );
+  const open =
+    storedOpen ??
+    (activity.state === "running" || activity.state === "action");
+  const hasDetails = Boolean(
+    activity.reasoning ||
+      activity.plan ||
+      activity.input ||
+      activity.sources?.length ||
+      activity.evidenceSources?.length ||
+      activity.excerpt ||
+      activity.detail,
+  );
+  const content = (
+    <div className="space-y-2 pb-3 pl-7 pr-1 text-[12.5px] text-muted-foreground">
+      {activity.input ? (
+        <p
+          className={cn(
+            "line-clamp-3 break-words rounded-xl bg-muted/45 px-3 py-2 text-foreground/80",
+            activity.kind === "step" &&
+              "bg-primary/[0.045] ring-1 ring-primary/10",
+          )}
+        >
+          {activity.input}
+        </p>
+      ) : null}
+      {activity.reasoning ? (
+        <div className="max-h-64 overflow-y-auto whitespace-pre-wrap break-words rounded-xl bg-muted/35 px-3 py-2 leading-relaxed text-foreground/80">
+          {activity.state === "running" && activity.reasoning.length > 8000
+            ? `…\n${activity.reasoning.slice(-8000)}`
+            : activity.reasoning}
+        </div>
+      ) : null}
+      {activity.plan ? (
+        <div className="space-y-2 rounded-xl bg-muted/35 px-3 py-2.5">
+          <p className="font-medium text-foreground/85">
+            {activity.plan.title}
+          </p>
+          {activity.plan.steps.slice(0, 3).map((step, index) => (
+            <div key={`activity-plan-${index}`} className="flex gap-2">
+              <span className="text-[10px] tabular-nums text-primary">
+                {index + 1}
+              </span>
+              <span className="min-w-0">
+                <span className="block font-medium text-foreground/80">
+                  {step.title}
+                </span>
+                <span className="line-clamp-2 break-words">{step.query}</span>
+              </span>
+            </div>
+          ))}
+          {activity.plan.steps.length > 3 ? (
+            <p className="pl-5 text-[11px] text-muted-foreground">
+              +{activity.plan.steps.length - 3} more steps
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+      {activity.detail ? (
+        <p
+          className={cn(
+            activity.kind === "step" &&
+              activity.state !== "failed" &&
+              "font-medium text-primary/75",
+          )}
+        >
+          {activity.detail}
+        </p>
+      ) : null}
+      {activity.sources?.map((source) => (
+        <button
+          key={`${activity.id}-${source.id ?? source.url}`}
+          type="button"
+          onClick={() => openLink(source.url)}
+          className="group/source flex w-full items-start gap-2 rounded-xl px-2 py-2 text-left transition-colors hover:bg-muted/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <Globe2 className="mt-0.5 size-3.5 shrink-0" />
+          <span className="min-w-0 flex-1">
+            <span className="block line-clamp-2 break-words font-medium text-foreground/85">
+              {source.title || source.url}
+            </span>
+            <span className="block truncate text-[11px]">{source.url}</span>
+            {source.snippet ? (
+              <span className="mt-1 block line-clamp-2 leading-relaxed">
+                {source.snippet}
+              </span>
+            ) : null}
+          </span>
+          <ExternalLink className="mt-0.5 size-3 opacity-0 transition-opacity group-hover/source:opacity-100" />
+        </button>
+      ))}
+      {activity.evidenceSources?.map((source) => (
+        <div
+          key={`${activity.id}-${source.chunkId}`}
+          className="rounded-xl bg-muted/45 px-3 py-2"
+        >
+          <p className="line-clamp-2 break-words font-medium text-foreground/85">
+            {source.filename}
+            {source.page ? ` · page ${source.page}` : ""}
+          </p>
+          {source.snippet ? (
+            <p className="mt-1 line-clamp-3 leading-relaxed">
+              {source.snippet}
+            </p>
+          ) : null}
+        </div>
+      ))}
+      {activity.excerpt ? (
+        <p className="line-clamp-5 whitespace-pre-wrap break-words rounded-xl bg-muted/45 px-3 py-2 leading-relaxed">
+          {activity.excerpt}
+        </p>
+      ) : null}
+    </div>
+  );
+
+  return (
+    <Collapsible
+      open={open}
+      onOpenChange={(nextOpen) =>
+        setActivityOpen(runId, activity.id, nextOpen)
+      }
+    >
+      <div
+        className={cn(
+          "relative pl-7 before:absolute before:left-[7px] before:top-6 before:h-[calc(100%-12px)] before:w-px before:bg-border last:before:hidden",
+          activity.kind === "step" && "before:bg-primary/20",
+        )}
+      >
+        <CollapsibleTrigger
+          disabled={!hasDetails}
+          className="group/activity flex min-h-10 w-full items-start gap-2 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default"
+        >
+          <span
+            className={cn(
+              "absolute left-0 top-3 flex size-[15px] items-center justify-center rounded-full bg-background text-muted-foreground",
+              activity.kind === "step" &&
+                activity.state !== "failed" &&
+                "bg-primary/10 text-primary",
+              activity.state === "failed" && "text-destructive",
+            )}
+          >
+            <ActivityIcon activity={activity} />
+          </span>
+          <span className="min-w-0 flex-1 break-words text-[13.5px] font-medium leading-5 text-foreground/90">
+            {activity.title}
+          </span>
+          <time className="mt-0.5 shrink-0 text-[10.5px] tabular-nums text-muted-foreground">
+            {new Date(activity.createdAt).toLocaleTimeString([], {
+              hour: "numeric",
+              minute: "2-digit",
+            })}
+          </time>
+          {hasDetails ? (
+            <ChevronDown className="mt-0.5 size-3.5 shrink-0 text-muted-foreground transition-transform group-data-[state=open]/activity:rotate-180" />
+          ) : null}
+        </CollapsibleTrigger>
+        {hasDetails ? <CollapsibleContent>{content}</CollapsibleContent> : null}
+      </div>
+    </Collapsible>
+  );
+});
+
+function PlanReview({ runId }: { runId: string }): ReactElement | null {
+  const run = useResearchRunStore((state) => state.sessions[runId]?.run);
+  const review = useResearchRunStore(
+    (state) => state.planReviewByRunId[runId],
+  );
+  const setOpen = useResearchRunStore((state) => state.setPlanReviewOpen);
+  const setEditing = useResearchRunStore(
+    (state) => state.setPlanReviewEditing,
+  );
+  const setDraft = useResearchRunStore((state) => state.setPlanReviewDraft);
+  const [pending, setPending] = useState(false);
+  const stepKeyPrefix = useId();
+  const [stepKeys, setStepKeys] = useState(() =>
+    (review?.draft.steps ?? []).map((_, index) => `${stepKeyPrefix}-${index}`),
+  );
+  const reduceMotion = useReducedMotion();
+
+  if (!run?.plan || run.status !== "awaiting_approval" || !review) return null;
+  const { draft, editing, open } = review;
+
+  const start = async () => {
+    setPending(true);
+    try {
+      let latest = run;
+      if (JSON.stringify(draft) !== JSON.stringify(run.plan)) {
+        latest = await updateResearchPlan(run.id, draft, run.planRevision);
+        ingestResearchUpdate(latest);
+      }
+      if (!latest.planHash)
+        throw new Error("The research plan is missing its approval hash.");
+      const approved = await approveResearchRun(
+        latest.id,
+        latest.planRevision,
+        latest.planHash,
+      );
+      ingestResearchUpdate(approved);
+    } catch (error) {
+      toast.error("Could not start research", {
+        description: error instanceof Error ? error.message : undefined,
+      });
+    } finally {
+      setPending(false);
+    }
+  };
+
+  const move = (index: number, direction: -1 | 1) => {
+    const target = index + direction;
+    if (target < 0 || target >= draft.steps.length) return;
+    const steps = [...draft.steps];
+    [steps[index], steps[target]] = [steps[target], steps[index]];
+    const keys = [...stepKeys];
+    [keys[index], keys[target]] = [keys[target], keys[index]];
+    setStepKeys(keys);
+    setDraft(runId, { ...draft, steps });
+  };
+
+  return (
+    <>
+      <section className="mx-4 mt-3 rounded-2xl border border-primary/20 bg-primary/[0.045] p-3">
+        <p className="font-heading text-sm font-medium">Research plan ready</p>
+        <p className="mt-1 line-clamp-2 break-words text-xs text-muted-foreground">
+          {run.plan.title}
+        </p>
+        <Button
+          className="mt-3 w-full"
+          size="sm"
+          onClick={() => setOpen(runId, true)}
+        >
+          Review plan
+        </Button>
+      </section>
+      <Dialog
+        open={open}
+        onOpenChange={(nextOpen) => setOpen(runId, nextOpen)}
+      >
+        <DialogContent className="max-h-[min(680px,calc(100dvh-6rem))] grid-rows-[auto_minmax(0,1fr)_auto] gap-0 overflow-hidden p-0 sm:max-w-3xl [&>[data-slot=dialog-close]]:right-6 [&>[data-slot=dialog-close]]:top-6">
+          <DialogHeader className="border-b border-border/70 px-7 pb-4 pt-6 pr-16">
+            <DialogTitle>Review the research plan</DialogTitle>
+            <DialogDescription className="max-w-2xl leading-relaxed">
+              Research starts only after your approval. Check the scope and
+              search approach before continuing.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="min-h-0 overflow-y-scroll px-7 py-5 [scrollbar-gutter:stable]">
+            {editing ? (
+              <div className="space-y-3">
+                <Textarea
+                  aria-label="Plan title"
+                  value={draft.title}
+                  maxLength={200}
+                  className="min-h-10 py-2 font-medium"
+                  onChange={(event) =>
+                    setDraft(runId, { ...draft, title: event.target.value })
+                  }
+                />
+                {draft.steps.map((step, index) => (
+                  <motion.div
+                    key={stepKeys[index] ?? `${stepKeyPrefix}-${index}`}
+                    layout="position"
+                    transition={
+                      reduceMotion
+                        ? { layout: { duration: 0 } }
+                        : {
+                            layout: {
+                              duration: 0.2,
+                              ease: [0.22, 1, 0.36, 1],
+                            },
+                          }
+                    }
+                    className="border-b border-border/60 py-3 first:pt-0 last:border-b-0 last:pb-0"
+                  >
+                    <div className="mb-2 flex items-center gap-1">
+                      <span className="mr-auto text-[11px] font-medium text-muted-foreground">
+                        Step {index + 1}
+                      </span>
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={() => move(index, -1)}
+                        disabled={index === 0}
+                        aria-label={`Move step ${index + 1} up`}
+                      >
+                        <ArrowUp />
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={() => move(index, 1)}
+                        disabled={index === draft.steps.length - 1}
+                        aria-label={`Move step ${index + 1} down`}
+                      >
+                        <ArrowDown />
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        disabled={draft.steps.length === 1}
+                        onClick={() => {
+                          setStepKeys((keys) => keys.filter(
+                            (_, stepIndex) => stepIndex !== index,
+                          ));
+                          setDraft(runId, {
+                            ...draft,
+                            steps: draft.steps.filter(
+                              (_, stepIndex) => stepIndex !== index,
+                            ),
+                          });
+                        }}
+                        aria-label={`Remove step ${index + 1}`}
+                      >
+                        <Trash2 />
+                      </Button>
+                    </div>
+                    <Textarea
+                      aria-label={`Step ${index + 1} title`}
+                      value={step.title}
+                      maxLength={200}
+                      className="mb-2 min-h-9 py-2"
+                      onChange={(event) => {
+                        const steps = [...draft.steps];
+                        steps[index] = { ...step, title: event.target.value };
+                        setDraft(runId, { ...draft, steps });
+                      }}
+                    />
+                    <Textarea
+                      aria-label={`Step ${index + 1} query`}
+                      value={step.query}
+                      maxLength={500}
+                      className="min-h-9 py-2 text-xs"
+                      onChange={(event) => {
+                        const steps = [...draft.steps];
+                        steps[index] = { ...step, query: event.target.value };
+                        setDraft(runId, { ...draft, steps });
+                      }}
+                    />
+                  </motion.div>
+                ))}
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  disabled={draft.steps.length >= 30}
+                  onClick={() => {
+                    setStepKeys((keys) => [
+                      ...keys,
+                      `${stepKeyPrefix}-${keys.length}-${Math.random().toString(36).slice(2)}`,
+                    ]);
+                    setDraft(runId, {
+                      ...draft,
+                      steps: [
+                        ...draft.steps,
+                        { title: "New research step", query: "" },
+                      ],
+                    });
+                  }}
+                >
+                  <Plus /> Add step
+                </Button>
+              </div>
+            ) : (
+              <div className="space-y-3">
+                <div className="mb-4 flex items-start justify-between gap-4">
+                  <p className="break-words font-heading text-lg font-medium leading-snug text-foreground/90">
+                    {draft.title}
+                  </p>
+                  <span className="shrink-0 rounded-full bg-muted px-2.5 py-1 text-[11px] font-medium text-muted-foreground">
+                    {draft.steps.length} steps
+                  </span>
+                </div>
+                {draft.steps.map((step, index) => (
+                  <div
+                    key={`${index}-${step.query}`}
+                    className="flex gap-3 border-b border-border/60 py-3 first:pt-0 last:border-b-0 last:pb-0"
+                  >
+                    <span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-primary/10 text-xs font-medium text-primary">
+                      {index + 1}
+                    </span>
+                    <span className="min-w-0">
+                      <span className="block break-words text-sm font-medium leading-5 text-foreground/90">
+                        {step.title}
+                      </span>
+                      <span className="mt-1 block break-words text-[13px] leading-relaxed text-muted-foreground/90">
+                        {step.query}
+                      </span>
+                    </span>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+          <DialogFooter className="shrink-0 flex-col gap-3 border-t border-border/70 bg-background px-7 py-4 sm:flex-row sm:items-center sm:justify-between">
+            <Button
+              variant="outline"
+              onClick={() => setEditing(runId, !editing)}
+            >
+              <Pencil /> {editing ? "Preview plan" : "Edit plan"}
+            </Button>
+            <div className="flex flex-col-reverse gap-2 sm:flex-row">
+              <Button variant="ghost" onClick={() => setOpen(runId, false)}>
+                Review later
+              </Button>
+              <Button
+                disabled={
+                  pending ||
+                  !draft.title.trim() ||
+                  draft.steps.some(
+                    (step) => !step.title.trim() || !step.query.trim(),
+                  )
+                }
+                onClick={() => void start()}
+              >
+                {pending ? <Spinner /> : <Telescope />}
+                {editing ? "Save and start" : "Start research"}
+              </Button>
+            </div>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+
+function ResearchActions({ runId }: { runId: string }): ReactElement | null {
+  const run = useResearchRunStore((state) => state.sessions[runId]?.run);
+  const [pending, setPending] = useState(false);
+  if (!run) return null;
+  const canRetry = run.status === "failed" || run.status === "cancelled";
+  if (!canRetry) return null;
+  const retry = async () => {
+    setPending(true);
+    try {
+      const retried = await retryResearchRun(run.id);
+      ingestResearchUpdate(retried);
+      useResearchRunStore.getState().setConnectionError(retried.id, null);
+      ensureResearchRunFollowed(retried.id, retried);
+    } catch (error) {
+      toast.error("Could not retry research", {
+        description: error instanceof Error ? error.message : undefined,
+      });
+    } finally {
+      setPending(false);
+    }
+  };
+
+  return (
+    <div className="border-t border-border/70 bg-background/95 p-3 backdrop-blur">
+      <Button
+        className="w-full"
+        disabled={pending}
+        onClick={() => void retry()}
+      >
+        {pending ? <Spinner /> : <RotateCcw />} Retry research
+      </Button>
+    </div>
+  );
+}
+
+export function ResearchActivityPanel({
+  runId,
+  onClose,
+  variant = "panel",
+}: {
+  runId: string;
+  onClose: () => void;
+  variant?: "panel" | "sheet";
+}): ReactElement {
+  const session = useResearchRunStore((state) => state.sessions[runId]);
+  const [elapsedNow, setElapsedNow] = useState<number | null>(null);
+  const { viewportRef, isAtBottom, scrollToLatest } =
+    useResearchActivityScroll(runId);
+  const hydrating = Boolean(
+    session &&
+      session.connection === "connecting" &&
+      session.lastAppliedSeq < session.run.lastEventSeq,
+  );
+
+  useEffect(() => {
+    ensureResearchRunFollowed(runId, session?.run);
+  }, [runId, session?.following]);
+
+  useEffect(() => {
+    if (!session || terminalStatuses.has(session.run.status)) return;
+    const timer = window.setInterval(() => setElapsedNow(Date.now()), 1000);
+    return () => window.clearInterval(timer);
+  }, [session?.run.status]);
+
+  if (!session) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <Spinner />
+      </div>
+    );
+  }
+  const { run, activities } = session;
+  const elapsedEnd = run.completedAt ?? elapsedNow ?? run.updatedAt;
+  const allowedDomains = run.config?.websitePolicy?.allowedDomains ?? [];
+  const blockedDomains = run.config?.websitePolicy?.blockedDomains ?? [];
+  const websiteLimitLabel = allowedDomains.length
+    ? allowedDomains.length === 1
+      ? `Only ${allowedDomains[0]}`
+      : `${allowedDomains.length} allowed domains`
+    : blockedDomains.length
+      ? `${blockedDomains.length} blocked ${blockedDomains.length === 1 ? "domain" : "domains"}`
+      : null;
+  const websiteLimitTitle = [
+    allowedDomains.length ? `Allowed: ${allowedDomains.join(", ")}` : "",
+    blockedDomains.length ? `Blocked: ${blockedDomains.join(", ")}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return (
+    <aside
+      aria-label="Research activity"
+      className="relative flex min-h-0 flex-col bg-background text-foreground"
+      style={
+        variant === "panel"
+          ? {
+              height:
+                "calc(100% - var(--studio-content-top-inset, 0px) - var(--studio-chat-header-height, 48px))",
+              marginTop:
+                "calc(var(--studio-content-top-inset, 0px) + var(--studio-chat-header-height, 48px))",
+            }
+          : {
+              height:
+                "calc(100% - var(--studio-custom-titlebar-height, 0px))",
+              marginTop: "var(--studio-custom-titlebar-height, 0px)",
+            }
+      }
+    >
+      <header className="shrink-0 border-b border-border/70 px-4 py-3.5">
+        <div className="flex items-start gap-3">
+          <div className="flex size-9 shrink-0 items-center justify-center rounded-[13px] bg-primary/10 text-primary">
+            <Telescope className="size-[18px]" />
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="flex items-center gap-2">
+              <h2 className="font-heading text-[15px] font-medium">
+                Deep research
+              </h2>
+              <span
+                className={cn(
+                  "rounded-full bg-muted px-2 py-0.5 text-[10.5px] font-medium text-muted-foreground",
+                  run.status === "awaiting_approval" &&
+                    "bg-amber-500/10 text-amber-700 dark:text-amber-300",
+                  run.status === "failed" &&
+                    "bg-destructive/10 text-destructive",
+                )}
+              >
+                {researchStatusLabel(run.status)}
+              </span>
+            </div>
+            <p className="mt-0.5 line-clamp-2 break-words text-xs text-muted-foreground">
+              {run.plan?.title ?? "Investigating your question"}
+            </p>
+            {websiteLimitLabel ? (
+              <p
+                className="mt-1 flex items-center gap-1 text-[10.5px] font-medium text-primary/75"
+                title={websiteLimitTitle}
+              >
+                <Globe2 className="size-3" />
+                <span className="truncate">{websiteLimitLabel}</span>
+              </p>
+            ) : null}
+            <p className="mt-1 text-[10.5px] tabular-nums text-muted-foreground">
+              {formatElapsed(run.createdAt, elapsedEnd)} · {run.sources.length}{" "}
+              sources ·{" "}
+              {run.steps.filter((step) => step.status === "completed").length}{" "}
+              actions
+            </p>
+          </div>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            onClick={onClose}
+            aria-label="Close research activity"
+          >
+            <X />
+          </Button>
+        </div>
+        {session.connection === "reconnecting" ? (
+          <div
+            role="status"
+            className="mt-2 flex items-center gap-2 text-[11px] text-amber-700 dark:text-amber-300"
+          >
+            <Spinner className="size-3" /> Reconnecting to research activity…
+          </div>
+        ) : session.connection === "disconnected" &&
+          !isSettledResearchRun(run, session.lastAppliedSeq) ? (
+          <div
+            role="status"
+            className="mt-2 flex items-center justify-between gap-2 text-[11px] text-destructive"
+          >
+            <span>Research activity is unavailable.</span>
+            <Button
+              size="sm"
+              variant="ghost"
+              className="h-7 px-2 text-[11px]"
+              onClick={() => {
+                useResearchRunStore
+                  .getState()
+                  .setConnectionError(runId, null);
+                ensureResearchRunFollowed(runId, run);
+              }}
+            >
+              Reconnect
+            </Button>
+          </div>
+        ) : null}
+      </header>
+      <PlanReview key={`${runId}-${run.planRevision}`} runId={runId} />
+      <div
+        ref={viewportRef}
+        role="log"
+        aria-live="off"
+        aria-label="Research activity timeline"
+        tabIndex={0}
+        className="min-h-0 flex-1 overflow-y-auto px-4 py-3 [overflow-anchor:none] focus-visible:outline-none"
+      >
+        {hydrating ? (
+          <div className="flex items-center gap-2 py-3 text-sm text-muted-foreground">
+            <Spinner /> Restoring research activity…
+          </div>
+        ) : activities.length ? (
+          activities.map((activity) => (
+            <ActivityRow key={activity.id} runId={runId} activity={activity} />
+          ))
+        ) : (
+          <div className="flex items-center gap-2 py-3 text-sm text-muted-foreground">
+            <Spinner /> Loading research activity…
+          </div>
+        )}
+      </div>
+      {isAtBottom ? null : (
+        <Button
+          size="sm"
+          variant="outline"
+          className="absolute bottom-16 left-1/2 z-10 -translate-x-1/2 bg-background"
+          onClick={scrollToLatest}
+        >
+          <ArrowDown /> Latest
+        </Button>
+      )}
+      <ResearchActions runId={runId} />
+    </aside>
+  );
+}
+
+export function ResearchActivitySheet({
+  runId,
+  open,
+  onOpenChange,
+}: {
+  runId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}): ReactElement {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        className="w-screen max-w-none p-0 sm:max-w-none"
+        showCloseButton={false}
+      >
+        <SheetHeader className="sr-only">
+          <SheetTitle>Deep research</SheetTitle>
+          <SheetDescription>Chronological research activity</SheetDescription>
+        </SheetHeader>
+        <ResearchActivityPanel
+          key={runId}
+          runId={runId}
+          onClose={() => onOpenChange(false)}
+          variant="sheet"
+        />
+      </SheetContent>
+    </Sheet>
+  );
+}

studio/frontend/src/features/chat/components/research-message.tsx

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { MarkdownPreview } from "@/components/markdown/markdown-preview";
+import {
+  type SourceData,
+  SourcesGroup,
+} from "@/components/assistant-ui/sources";
+import { Button } from "@/components/ui/button";
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import { useAuiState } from "@assistant-ui/react";
+import {
+  Check,
+  Telescope,
+  TriangleAlert,
+} from "lucide-react";
+import { type ReactElement, useEffect } from "react";
+import {
+  ensureResearchRunFollowed,
+  ingestResearchUpdate,
+  useResearchRunStore,
+} from "../stores/research-run-store";
+import type { ResearchMessageMetadata } from "../types/research";
+import { researchStatusLabel } from "./research-activity-panel";
+
+export function ResearchMessage(): ReactElement {
+  const metadata = useAuiState(
+    ({ message }) =>
+      (message.metadata as { custom?: ResearchMessageMetadata } | undefined)
+        ?.custom ?? {},
+  );
+  const fallbackText = useAuiState(({ message }) =>
+    message.parts
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n"),
+  );
+  const runId = metadata.researchRunId ?? metadata.researchRun?.id ?? "";
+  const session = useResearchRunStore((state) => state.sessions[runId]);
+  const openPanel = useResearchRunStore((state) => state.openPanel);
+  const initialRun = metadata.researchRun;
+
+  useEffect(() => {
+    if (!runId) {
+      return;
+    }
+    if (initialRun) {
+      ingestResearchUpdate(initialRun);
+    }
+    if (!session?.following) {
+      ensureResearchRunFollowed(runId, initialRun);
+    }
+  }, [runId, initialRun, session?.following]);
+
+  const run = session?.run ?? metadata.researchRun;
+  if (!run) {
+    if (fallbackText.trim()) {
+      return (
+        <MarkdownPreview
+          markdown={fallbackText}
+          className="max-h-none overflow-visible border-0 bg-transparent p-0 text-[15.5px]"
+        />
+      );
+    }
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Spinner /> Loading research…
+      </div>
+    );
+  }
+
+  if (run.status === "completed" && run.report) {
+    const sources: SourceData[] = run.sources.map((source) => ({
+      id: String(source.id ?? source.url),
+      url: source.url,
+      title: source.title || source.url,
+      description: source.snippet ?? undefined,
+    }));
+    return (
+      <div className="min-w-0">
+        <button
+          type="button"
+          onClick={() => openPanel(run.id)}
+          className="mb-3 flex items-center gap-2 rounded-full text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <span className="flex size-5 items-center justify-center rounded-full bg-primary/10 text-primary">
+            <Check className="size-3" />
+          </span>
+          <span>Deep research completed · {run.sources.length} sources</span>
+          <span className="text-primary">View activity</span>
+        </button>
+        <MarkdownPreview
+          markdown={run.report}
+          className="max-h-none overflow-visible border-0 bg-transparent p-0 text-[15.5px]"
+        />
+        <SourcesGroup sources={sources} />
+      </div>
+    );
+  }
+
+  const failed = run.status === "failed";
+  const cancelled = run.status === "cancelled";
+  const needsApproval = run.status === "awaiting_approval";
+  return (
+    <div
+      className={cn(
+        "rounded-[22px] border border-border/70 bg-card/65 p-4",
+        needsApproval && "border-amber-500/25 bg-amber-500/[0.035]",
+        failed && "border-destructive/25 bg-destructive/[0.025]",
+      )}
+    >
+      <div className="flex items-start gap-3">
+        <span
+          className={cn(
+            "mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-[12px] bg-primary/10 text-primary",
+            failed && "bg-destructive/10 text-destructive",
+          )}
+        >
+          {failed ? (
+            <TriangleAlert className="size-4" />
+          ) : cancelled ? (
+            <Telescope className="size-4" />
+          ) : (
+            <Spinner className="size-4" />
+          )}
+        </span>
+        <div className="min-w-0 flex-1">
+          <p className="font-heading text-sm font-medium">
+            {failed
+              ? "Research could not be completed"
+              : cancelled
+                ? "Research stopped"
+                : needsApproval
+                  ? "Your research plan is ready"
+                  : researchStatusLabel(run.status)}
+          </p>
+          <p className="mt-1 text-[12.5px] leading-relaxed text-muted-foreground">
+            {session?.error
+              ? session.error
+              : failed
+                ? run.error
+                : needsApproval
+                  ? "Review the approach before the agent starts gathering evidence."
+                  : cancelled
+                    ? "The activity gathered so far is still available."
+                    : (run.plan?.title ?? "Building a rigorous research plan…")}
+          </p>
+          <Button
+            size="sm"
+            variant={needsApproval ? "default" : "outline"}
+            className="mt-3"
+            onClick={() => openPanel(run.id)}
+          >
+            {needsApproval ? "Review plan" : "View activity"}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

studio/frontend/src/features/chat/index.ts

@@ -47,6 +47,11 @@ export type { ProjectRecord } from "./types";
 export { clearAllChats, countAllChats } from "./utils/clear-all-chats";
 export { listStoredChatThreads } from "./utils/chat-history-storage";
 export { ArtifactCard } from "./artifacts/artifact-card";
+export { ResearchMessage } from "./components/research-message";
+export {
+  ResearchActivityPanel,
+  ResearchActivitySheet,
+} from "./components/research-activity-panel";
 export {
   useChatArtifactsStore,
   useSelectedChatArtifact,

studio/frontend/src/features/chat/runtime-provider.tsx

@@ -39,6 +39,11 @@ import {
   ThreadAutosaveHandle,
   createOpenAIStreamAdapter,
 } from "./api/chat-adapter";
+import { getResearchThreadState } from "./api/research-api";
+import {
+  ingestResearchUpdate,
+  useResearchRunStore,
+} from "./stores/research-run-store";
 import {
   loadConnectionsEnabled,
   loadExternalProviders,
@@ -842,26 +847,33 @@ function trackRunStartReady(
 async function waitForRunStartHistoryAppend(
   messages: Parameters<ChatModelAdapter["run"]>[0]["messages"],
 ): Promise<void> {
-  const lastMessage = messages.at(-1);
-  if (!lastMessage || lastMessage.role !== "user") {
+  // Deep Research reserves an assistant placeholder before invoking the model
+  // adapter, so the user message is not necessarily the final entry here.
+  const userMessage = [...messages]
+    .reverse()
+    .find((message) => message.role === "user");
+  if (!userMessage) {
     return;
   }
-  const ready =
-    pendingRunStartReadyByMessageId.get(lastMessage.id) ??
-    pendingHistoryAppendByMessageId.get(lastMessage.id);
-  if (!ready) {
+  const runStartReady = pendingRunStartReadyByMessageId.get(userMessage.id);
+  const historyAppendReady = pendingHistoryAppendByMessageId.get(userMessage.id);
+  const pending = [runStartReady, historyAppendReady].filter(
+    (ready): ready is Promise<void> => ready !== undefined,
+  );
+  if (pending.length === 0) {
     return;
   }
   let didBecomeReady = false;
   try {
-    await ready;
+    await Promise.all(pending);
     didBecomeReady = true;
   } finally {
     if (
       didBecomeReady &&
-      pendingRunStartReadyByMessageId.get(lastMessage.id) === ready
+      runStartReady &&
+      pendingRunStartReadyByMessageId.get(userMessage.id) === runStartReady
     ) {
-      pendingRunStartReadyByMessageId.delete(lastMessage.id);
+      pendingRunStartReadyByMessageId.delete(userMessage.id);
     }
   }
 }
@@ -911,6 +923,32 @@ function useStudioRuntimeAdapters(
           }
           msgs = [];
         }
+        // Durable research can outlive this runtime. Reattach its server-owned
+        // assistant message to the inline card after navigation or refresh.
+        const researchThreadState = await getResearchThreadState(remoteId).catch(
+          () => null,
+        );
+        if (researchThreadState) {
+          useResearchRunStore
+            .getState()
+            .setThreadClaimed(remoteId, researchThreadState.hasRun);
+        }
+        const activeResearchRun = researchThreadState?.activeRun ?? null;
+        if (activeResearchRun) ingestResearchUpdate(activeResearchRun);
+        if (activeResearchRun?.assistantMessageId) {
+          const assistant = msgs.find(
+            (message) => message.id === activeResearchRun.assistantMessageId,
+          );
+          if (assistant) {
+            assistant.metadata = {
+              ...(assistant.metadata ?? {}),
+              researchRunId: activeResearchRun.id,
+              researchRun: activeResearchRun,
+              serverManaged: true,
+              serverRevision: activeResearchRun.lastEventSeq,
+            };
+          }
+        }
         msgs.sort((a, b) => {
           if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
           const aOrder = roleOrder[a.role] ?? 99;
@@ -1009,16 +1047,34 @@ function useStudioRuntimeAdapters(
           const createdAt =
             existingMessage?.createdAt ??
             message.createdAt?.getTime?.() ??
-            Date.now();
+              Date.now();
+          const existingMetadata = existingMessage?.metadata;
+          const incomingRevision = Number(
+            (custom as Record<string, unknown> | undefined)?.serverRevision ?? -1,
+          );
+          const existingRevision = Number(existingMetadata?.serverRevision ?? -1);
+          const incomingMetadata = custom as
+            | Record<string, unknown>
+            | undefined;
+          const sameResearchRun =
+            typeof existingMetadata?.researchRunId === "string" &&
+            existingMetadata.researchRunId === incomingMetadata?.researchRunId;
+          const preserveServerManaged =
+            existingMetadata?.serverManaged === true &&
+            (sameResearchRun ||
+              !incomingMetadata?.serverManaged ||
+              existingRevision > incomingRevision);
+          const metadata = preserveServerManaged
+            ? { ...incomingMetadata, ...existingMetadata }
+            : incomingMetadata;
           await saveStoredChatMessage({
             id: message.id,
             threadId: remoteId,
             parentId: parentId ?? null,
             role: message.role,
-            content,
+            content: preserveServerManaged ? existingMessage!.content : content,
             ...(attachments.length > 0 && { attachments }),
-            ...(custom &&
-              Object.keys(custom).length > 0 && { metadata: custom }),
+            ...(metadata && { metadata }),
             createdAt,
           });
         })();

studio/frontend/src/features/chat/stores/chat-runtime-store.ts

@@ -26,6 +26,7 @@ import {
   loadChatSettingsWithLegacyImport,
   savePersistedChatSettingsPatch,
 } from "../utils/chat-settings-storage";
+import type { ResearchWebsitePolicy } from "../types/research";
 import { useExternalProvidersStore } from "./external-providers-store";
 import { PLUS_MENU_PINS_STORAGE_KEY } from "./plus-menu-prefs-store";
 
@@ -33,6 +34,10 @@ export const CHAT_REASONING_ENABLED_KEY = "unsloth_chat_reasoning_enabled";
 export const CHAT_TOOLS_ENABLED_KEY = "unsloth_chat_tools_enabled";
 export const CHAT_CODE_TOOLS_ENABLED_KEY = "unsloth_chat_code_tools_enabled";
 export const CHAT_IMAGE_TOOLS_ENABLED_KEY = "unsloth_chat_image_tools_enabled";
+export const CHAT_DEEP_RESEARCH_ENABLED_KEY =
+  "unsloth_chat_deep_research_enabled";
+export const CHAT_DEEP_RESEARCH_WEBSITE_POLICY_KEY =
+  "unsloth_chat_deep_research_website_policy";
 export const CHAT_ARTIFACTS_ENABLED_KEY = "unsloth_chat_artifacts_enabled";
 export const CHAT_SHOW_CANVAS_MENU_ITEM_KEY =
   "unsloth_chat_show_canvas_menu_item";
@@ -97,6 +102,45 @@ export const DEFAULT_RAG_OCR = true;
 // Describe figures/charts in PDFs at ingest time so they become searchable. On by
 // default (no-op without a vision model); off skips the per-figure vision calls.
 export const DEFAULT_RAG_CAPTION = true;
+export const DEFAULT_RESEARCH_WEBSITE_POLICY: ResearchWebsitePolicy = {
+  allowedDomains: [],
+  blockedDomains: [],
+};
+
+function loadResearchWebsitePolicy(): ResearchWebsitePolicy {
+  if (typeof window === "undefined") return DEFAULT_RESEARCH_WEBSITE_POLICY;
+  try {
+    const parsed = JSON.parse(
+      window.localStorage.getItem(CHAT_DEEP_RESEARCH_WEBSITE_POLICY_KEY) || "{}",
+    ) as Partial<ResearchWebsitePolicy>;
+    return {
+      allowedDomains: Array.isArray(parsed.allowedDomains)
+        ? parsed.allowedDomains.filter(
+            (value): value is string => typeof value === "string",
+          )
+        : [],
+      blockedDomains: Array.isArray(parsed.blockedDomains)
+        ? parsed.blockedDomains.filter(
+            (value): value is string => typeof value === "string",
+          )
+        : [],
+    };
+  } catch {
+    return DEFAULT_RESEARCH_WEBSITE_POLICY;
+  }
+}
+
+function saveResearchWebsitePolicy(policy: ResearchWebsitePolicy): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      CHAT_DEEP_RESEARCH_WEBSITE_POLICY_KEY,
+      JSON.stringify(policy),
+    );
+  } catch {
+    // Keep the in-memory setting when storage is unavailable.
+  }
+}
 
 function loadRagSource(): RagSource {
   if (typeof window === "undefined") return DEFAULT_RAG_SOURCE;
@@ -653,6 +697,8 @@ type ChatRuntimeStore = {
   toolsEnabled: boolean;
   codeToolsEnabled: boolean;
   imageToolsEnabled: boolean;
+  deepResearchEnabled: boolean;
+  researchWebsitePolicy: ResearchWebsitePolicy;
   artifactsEnabled: boolean;
   // Whether the Canvas toggle is offered in the composer + menu (hidden by default).
   showCanvasMenuItem: boolean;
@@ -828,6 +874,8 @@ type ChatRuntimeStore = {
   setToolsEnabled: (enabled: boolean, options?: { persist?: boolean }) => void;
   setCodeToolsEnabled: (enabled: boolean) => void;
   setImageToolsEnabled: (enabled: boolean) => void;
+  setDeepResearchEnabled: (enabled: boolean) => void;
+  setResearchWebsitePolicy: (policy: ResearchWebsitePolicy) => void;
   setArtifactsEnabled: (
     enabled: boolean,
     options?: { persist?: boolean },
@@ -1161,6 +1209,8 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   toolsEnabled: loadBool(CHAT_TOOLS_ENABLED_KEY, false),
   codeToolsEnabled: loadBool(CHAT_CODE_TOOLS_ENABLED_KEY, false),
   imageToolsEnabled: loadBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, false),
+  deepResearchEnabled: loadBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false),
+  researchWebsitePolicy: loadResearchWebsitePolicy(),
   artifactsEnabled: loadBool(CHAT_ARTIFACTS_ENABLED_KEY, false),
   showCanvasMenuItem: loadShowCanvasMenuItem(),
   collapseHtmlArtifacts: loadBool(CHAT_COLLAPSE_HTML_ARTIFACTS_KEY, false),
@@ -1350,6 +1400,9 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       // stale persisted local id would race the freshly-loaded model. See
       // LAST_EXTERNAL_CHECKPOINT_KEY notes.
       saveLastExternalCheckpoint(isExternalModelId(modelId) ? modelId : null);
+      if (isExternalModelId(modelId)) {
+        saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      }
       // Clear stale per-turn usage on model change; the relaxed external-provider
       // render gate would otherwise show old counters until the next completion.
       const checkpointChanged = state.params.checkpoint !== modelId;
@@ -1395,12 +1448,20 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
         ...(pendingToClear
           ? { ...loadedBaselineSettings(state), pendingSelection: null }
           : {}),
+        ...(isExternalModelId(modelId) ? { deepResearchEnabled: false } : {}),
       };
     }),
   setActiveThreadId: (activeThreadId) =>
     set({ activeThreadId, contextUsage: null }),
   setActiveProjectId: (activeProjectId) => set({ activeProjectId }),
-  setIncognito: (incognito) => set({ incognito }),
+  setIncognito: (incognito) => {
+    if (incognito) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+    set(
+      incognito
+        ? { incognito, deepResearchEnabled: false }
+        : { incognito },
+    );
+  },
   setSettingsPanelOpen: (settingsPanelOpen) => set({ settingsPanelOpen }),
   setEditingMessageId: (id) => set({ editingMessageId: id }),
   clearCheckpoint: () => {
@@ -1408,6 +1469,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
     // clear any stored external selection so the next refresh doesn't snap
     // back to a model the user intentionally cleared.
     saveLastExternalCheckpoint(null);
+    saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
     cancelStagedModelDownload(get().pendingSelection);
     return set((state) => ({
       params: {
@@ -1437,6 +1499,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       toolsEnabled: false,
       codeToolsEnabled: false,
       imageToolsEnabled: false,
+      deepResearchEnabled: false,
       artifactsEnabled: false,
       mcpEnabledForChat: false,
       webFetchToolsEnabled: false,
@@ -1497,24 +1560,63 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       if (options?.persist !== false) {
         saveBool(CHAT_TOOLS_ENABLED_KEY, toolsEnabled);
       }
-      return { toolsEnabled };
+      if (toolsEnabled) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      return toolsEnabled ? { toolsEnabled, deepResearchEnabled: false } : { toolsEnabled };
     }),
   setCodeToolsEnabled: (codeToolsEnabled) =>
     set(() => {
       saveBool(CHAT_CODE_TOOLS_ENABLED_KEY, codeToolsEnabled);
-      return { codeToolsEnabled };
+      if (codeToolsEnabled) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      return codeToolsEnabled
+        ? { codeToolsEnabled, deepResearchEnabled: false }
+        : { codeToolsEnabled };
     }),
   setImageToolsEnabled: (imageToolsEnabled) =>
     set(() => {
       saveBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, imageToolsEnabled);
-      return { imageToolsEnabled };
+      if (imageToolsEnabled) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      return imageToolsEnabled
+        ? { imageToolsEnabled, deepResearchEnabled: false }
+        : { imageToolsEnabled };
+    }),
+  setDeepResearchEnabled: (deepResearchEnabled) =>
+    set(() => {
+      saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, deepResearchEnabled);
+      if (deepResearchEnabled) {
+        saveBool(CHAT_TOOLS_ENABLED_KEY, false);
+        saveBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, false);
+        saveBool(CHAT_CODE_TOOLS_ENABLED_KEY, false);
+        saveBool(CHAT_ARTIFACTS_ENABLED_KEY, false);
+        saveBool(CHAT_MCP_ENABLED_KEY, false);
+        saveBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, false);
+      }
+      return deepResearchEnabled
+        ? {
+            deepResearchEnabled,
+            toolsEnabled: false,
+            codeToolsEnabled: false,
+            imageToolsEnabled: false,
+            artifactsEnabled: false,
+            mcpEnabledForChat: false,
+            webFetchToolsEnabled: false,
+            bypassPermissions: false,
+          }
+        : { deepResearchEnabled };
+    }),
+  setResearchWebsitePolicy: (researchWebsitePolicy) =>
+    set(() => {
+      saveResearchWebsitePolicy(researchWebsitePolicy);
+      return { researchWebsitePolicy };
     }),
   setArtifactsEnabled: (artifactsEnabled, options) =>
     set(() => {
       if (options?.persist !== false) {
         saveBool(CHAT_ARTIFACTS_ENABLED_KEY, artifactsEnabled);
       }
-      return { artifactsEnabled };
+      if (artifactsEnabled) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      return artifactsEnabled
+        ? { artifactsEnabled, deepResearchEnabled: false }
+        : { artifactsEnabled };
     }),
   setShowCanvasMenuItem: (showCanvasMenuItem) =>
     set(() => {
@@ -1547,7 +1649,10 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   setMcpEnabledForChat: (mcpEnabledForChat) =>
     set(() => {
       saveBool(CHAT_MCP_ENABLED_KEY, mcpEnabledForChat);
-      return { mcpEnabledForChat };
+      if (mcpEnabledForChat) saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
+      return mcpEnabledForChat
+        ? { mcpEnabledForChat, deepResearchEnabled: false }
+        : { mcpEnabledForChat };
     }),
   setConfirmToolCalls: (confirmToolCalls) =>
     set((state) => {
@@ -1584,10 +1689,12 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       if (bypassPermissions) {
         // Full access never prompts; mirror confirm_tool_calls=false in the
         // store so metadata does not report confirmations as enabled.
+        saveBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false);
         return {
           bypassPermissions,
           permissionMode: "full" as PermissionMode,
           confirmToolCalls: false,
+          deepResearchEnabled: false,
         };
       }
       const permissionMode = loadPermissionMode();

studio/frontend/src/features/chat/stores/research-run-store.ts

@@ -0,0 +1,869 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { create } from "zustand";
+import { AUTH_SESSION_CLEARED_EVENT } from "@/features/auth";
+import { followResearchRun, type ResearchRunUpdate } from "../api/research-api";
+import type {
+  ResearchAction,
+  ResearchEvent,
+  ResearchEvidenceSource,
+  ResearchPhase,
+  ResearchPlan,
+  ResearchRun,
+  ResearchSource,
+} from "../types/research";
+
+export type ResearchConnectionState =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "disconnected";
+
+export interface ResearchActivity {
+  id: string;
+  seq: number;
+  attempt: number;
+  kind: "status" | "reasoning" | "plan" | "step" | "report";
+  createdAt: number;
+  title: string;
+  detail?: string;
+  state?: "running" | "complete" | "failed" | "cancelled" | "action";
+  phase?: ResearchPhase;
+  reasoning?: string;
+  plan?: ResearchPlan;
+  stepPosition?: number;
+  action?: ResearchAction;
+  input?: string;
+  sources?: ResearchSource[];
+  evidenceSources?: ResearchEvidenceSource[];
+  excerpt?: string;
+}
+
+export interface ResearchSession {
+  run: ResearchRun;
+  activities: ResearchActivity[];
+  lastAppliedSeq: number;
+  following: boolean;
+  connection: ResearchConnectionState;
+  error: string | null;
+}
+
+export interface ResearchPlanReviewState {
+  revision: number;
+  open: boolean;
+  editing: boolean;
+  draft: ResearchPlan;
+}
+
+interface ResearchRunState {
+  sessions: Record<string, ResearchSession>;
+  latestRunByThreadId: Record<string, string>;
+  claimedThreadIds: Record<string, boolean>;
+  activityOpenByRunId: Record<string, Record<string, boolean>>;
+  planReviewByRunId: Record<string, ResearchPlanReviewState>;
+  openRunId: string | null;
+  ingest: (run: ResearchRun, event?: ResearchEvent) => void;
+  setThreadClaimed: (threadId: string, claimed: boolean) => void;
+  setFollowing: (
+    runId: string,
+    following: boolean,
+    connection?: ResearchConnectionState,
+  ) => void;
+  setConnectionError: (runId: string, error: string | null) => void;
+  openPanel: (runId: string) => void;
+  closePanel: () => void;
+  setActivityOpen: (runId: string, activityId: string, open: boolean) => void;
+  setPlanReviewOpen: (runId: string, open: boolean) => void;
+  setPlanReviewEditing: (runId: string, editing: boolean) => void;
+  setPlanReviewDraft: (runId: string, draft: ResearchPlan) => void;
+}
+
+const terminalStatuses = new Set(["completed", "failed", "cancelled"]);
+
+export function isSettledResearchRun(
+  run: ResearchRun,
+  lastAppliedSeq: number,
+): boolean {
+  return terminalStatuses.has(run.status) && lastAppliedSeq >= run.lastEventSeq;
+}
+
+function statusActivity(event: ResearchEvent): ResearchActivity | null {
+  const attempt = event.data.attempt ?? 0;
+  const base = {
+    id: `event-${event.id}`,
+    seq: event.id,
+    attempt,
+    kind: "status" as const,
+    createdAt: event.createdAt,
+  };
+  switch (event.event) {
+    case "run.created":
+      return { ...base, title: "Research requested", state: "complete" };
+    case "run.started":
+      return event.data.status === "planning"
+        ? null
+        : {
+            ...base,
+            title: attempt > 0 ? "Research resumed" : "Research started",
+            state: "complete",
+          };
+    case "run.approved":
+      return { ...base, title: "Plan approved", state: "complete" };
+    case "run.cancelRequested":
+      return { ...base, title: "Stopping research safely", state: "running" };
+    case "run.cancelled":
+      return { ...base, title: "Research cancelled", state: "cancelled" };
+    case "run.retried":
+      return {
+        ...base,
+        title: `Started attempt ${attempt + 1}`,
+        detail: "Previous activity is preserved below.",
+        state: "complete",
+      };
+    case "run.completed":
+      return { ...base, title: "Research completed", state: "complete" };
+    case "run.failed":
+      return {
+        ...base,
+        title: "Research failed",
+        detail: event.data.error ?? undefined,
+        state: "failed",
+      };
+    default:
+      return null;
+  }
+}
+
+function findLastActivityIndex(
+  activities: ResearchActivity[],
+  predicate: (activity: ResearchActivity) => boolean,
+): number {
+  for (let index = activities.length - 1; index >= 0; index -= 1) {
+    if (predicate(activities[index])) return index;
+  }
+  return -1;
+}
+
+function syncPlanReviewState(
+  current: ResearchPlanReviewState | undefined,
+  run: ResearchRun,
+): ResearchPlanReviewState | undefined {
+  if (!run.plan || run.status !== "awaiting_approval") return current;
+  if (current?.revision === run.planRevision) return current;
+  return {
+    revision: run.planRevision,
+    open: true,
+    editing: false,
+    draft: run.plan,
+  };
+}
+
+function reduceActivity(
+  activities: ResearchActivity[],
+  event: ResearchEvent,
+): ResearchActivity[] {
+  const next = [...activities];
+  const attempt = event.data.attempt ?? 0;
+  if (event.event !== "reasoning.updated") {
+    const activeReasoningIndex = findLastActivityIndex(
+      next,
+      (activity) =>
+        activity.kind === "reasoning" && activity.state === "running",
+    );
+    if (activeReasoningIndex >= 0) {
+      next[activeReasoningIndex] = {
+        ...next[activeReasoningIndex],
+        state: "complete",
+      };
+    }
+  }
+  if (event.event === "reasoning.updated") {
+    const phase = event.data.phase ?? "unknown";
+    const callId = event.data.callId ?? `${phase}-${event.id}`;
+    const id = `reasoning-${attempt}-${callId}`;
+    const existingIndex = next.findIndex((activity) => activity.id === id);
+    const delta = event.data.reasoningDelta ?? "";
+    const title =
+      phase === "planning"
+        ? "Planning an approach"
+        : phase === "synthesis"
+          ? "Connecting the findings"
+          : "Choosing the next step";
+    if (existingIndex >= 0) {
+      const existing = next[existingIndex];
+      next[existingIndex] = {
+        ...existing,
+        seq: event.id,
+        reasoning: `${existing.reasoning ?? ""}${delta}`,
+        state: "running",
+      };
+    } else {
+      const activeReasoningIndex = findLastActivityIndex(
+        next,
+        (activity) =>
+          activity.kind === "reasoning" && activity.state === "running",
+      );
+      if (activeReasoningIndex >= 0) {
+        next[activeReasoningIndex] = {
+          ...next[activeReasoningIndex],
+          state: "complete",
+        };
+      }
+      next.push({
+        id,
+        seq: event.id,
+        attempt,
+        kind: "reasoning",
+        createdAt: event.createdAt,
+        title,
+        phase,
+        reasoning: delta,
+        state: "running",
+        stepPosition: event.data.stepPosition,
+      });
+    }
+    return next;
+  }
+
+  if (event.event === "plan.ready") {
+    next.push({
+      id: `plan-${attempt}-${event.data.planRevision ?? event.id}`,
+      seq: event.id,
+      attempt,
+      kind: "plan",
+      createdAt: event.createdAt,
+      title: "Research plan ready",
+      plan: event.data.plan ?? event.run.plan ?? undefined,
+      state: "action",
+    });
+    return next;
+  }
+
+  if (event.event === "run.approved") {
+    const planIndex = findLastActivityIndex(
+      next,
+      (activity) =>
+        activity.kind === "plan" &&
+        activity.attempt === attempt &&
+        activity.state === "action",
+    );
+    if (planIndex >= 0) {
+      next[planIndex] = {
+        ...next[planIndex],
+        seq: event.id,
+        state: "complete",
+      };
+    }
+  }
+
+  if (event.event === "step.started") {
+    const action = event.data.action ?? "search";
+    next.push({
+      id: `step-${attempt}-${event.data.stepPosition ?? event.id}`,
+      seq: event.id,
+      attempt,
+      kind: "step",
+      createdAt: event.createdAt,
+      title:
+        event.data.title ??
+        (action === "fetch" ? "Reading a page" : "Searching the web"),
+      detail: action === "fetch" ? "Reading page" : "Web search",
+      state: "running",
+      stepPosition: event.data.stepPosition ?? event.data.position,
+      action,
+      input: event.data.input,
+      sources: [],
+    });
+    return next;
+  }
+
+  if (event.event === "source.added") {
+    const stepPosition = event.data.stepPosition ?? event.data.position;
+    const index = findLastActivityIndex(
+      next,
+      (activity) =>
+        activity.kind === "step" &&
+        activity.attempt === attempt &&
+        activity.stepPosition === stepPosition,
+    );
+    if (index >= 0 && event.data.url) {
+      const activity = next[index];
+      const source: ResearchSource = {
+        id: `${event.id}`,
+        stepPosition,
+        url: event.data.url,
+        title: event.data.title ?? event.data.url,
+        snippet: event.data.snippet,
+        fetchedAt: event.data.fetchedAt,
+      };
+      next[index] = {
+        ...activity,
+        sources: [...(activity.sources ?? []), source],
+      };
+    }
+    return next;
+  }
+
+  if (event.event === "step.completed" || event.event === "step.failed") {
+    const stepPosition = event.data.stepPosition ?? event.data.position;
+    const index = findLastActivityIndex(
+      next,
+      (activity) =>
+        activity.kind === "step" &&
+        activity.attempt === attempt &&
+        activity.stepPosition === stepPosition,
+    );
+    if (index >= 0) {
+      const activity = next[index];
+      const snapshot = event.run.steps.find(
+        (step) => step.position === stepPosition,
+      );
+      next[index] = {
+        ...activity,
+        seq: event.id,
+        state: event.event === "step.failed" ? "failed" : "complete",
+        detail:
+          event.event === "step.failed"
+            ? (event.data.error ?? "The tool could not complete this action.")
+            : `${event.data.sourceCount ?? activity.sources?.length ?? 0} sources found`,
+        evidenceSources: snapshot?.result?.evidenceSources,
+        excerpt: snapshot?.result?.excerpt,
+      };
+    }
+    return next;
+  }
+
+  if (event.event === "report.updated") {
+    const id = `report-${attempt}`;
+    const index = next.findIndex((activity) => activity.id === id);
+    if (index >= 0) {
+      next[index] = { ...next[index], seq: event.id, state: "running" };
+    } else {
+      next.push({
+        id,
+        seq: event.id,
+        attempt,
+        kind: "report",
+        createdAt: event.createdAt,
+        title: "Writing the report",
+        state: "running",
+      });
+    }
+    return next;
+  }
+
+  if (
+    event.event === "run.completed" ||
+    event.event === "run.failed" ||
+    event.event === "run.cancelled"
+  ) {
+    const terminalState =
+      event.event === "run.completed"
+        ? "complete"
+        : event.event === "run.failed"
+          ? "failed"
+          : "cancelled";
+    for (let index = 0; index < next.length; index += 1) {
+      const activity = next[index];
+      if (activity.attempt === attempt && activity.state === "running") {
+        next[index] = { ...activity, seq: event.id, state: terminalState };
+      }
+    }
+  }
+
+  const status = statusActivity(event);
+  if (status) next.push(status);
+  return next;
+}
+
+export const useResearchRunStore = create<ResearchRunState>((set) => ({
+  sessions: {},
+  latestRunByThreadId: {},
+  claimedThreadIds: {},
+  activityOpenByRunId: {},
+  planReviewByRunId: {},
+  openRunId: null,
+  ingest: (run, event) =>
+    set((state) => {
+      const previous = state.sessions[run.id];
+      if (event && previous && event.id <= previous.lastAppliedSeq)
+        return state;
+      if (
+        !event &&
+        previous &&
+        (run.lastEventSeq < previous.run.lastEventSeq ||
+          run.updatedAt < previous.run.updatedAt)
+      ) {
+        return state;
+      }
+      const activities = event
+        ? reduceActivity(previous?.activities ?? [], event)
+        : (previous?.activities ?? []);
+      const lastAppliedSeq = event?.id ?? previous?.lastAppliedSeq ?? 0;
+      const settled = isSettledResearchRun(run, lastAppliedSeq);
+      const session: ResearchSession = {
+        run,
+        activities,
+        lastAppliedSeq,
+        following: settled ? false : (previous?.following ?? false),
+        connection: settled ? "idle" : (previous?.connection ?? "idle"),
+        error: settled ? null : (previous?.error ?? null),
+      };
+      const currentLatestId = state.latestRunByThreadId[run.threadId];
+      const currentLatestRun = currentLatestId
+        ? state.sessions[currentLatestId]?.run
+        : undefined;
+      const shouldBecomeLatest =
+        !currentLatestRun ||
+        currentLatestRun.id === run.id ||
+        run.createdAt >= currentLatestRun.createdAt;
+      const planReview = syncPlanReviewState(
+        state.planReviewByRunId[run.id],
+        run,
+      );
+      return {
+        sessions: { ...state.sessions, [run.id]: session },
+        claimedThreadIds: state.claimedThreadIds[run.threadId]
+          ? state.claimedThreadIds
+          : { ...state.claimedThreadIds, [run.threadId]: true },
+        latestRunByThreadId: shouldBecomeLatest
+          ? { ...state.latestRunByThreadId, [run.threadId]: run.id }
+          : state.latestRunByThreadId,
+        ...(planReview && planReview !== state.planReviewByRunId[run.id]
+          ? {
+              planReviewByRunId: {
+                ...state.planReviewByRunId,
+                [run.id]: planReview,
+              },
+            }
+          : {}),
+      };
+    }),
+  setThreadClaimed: (threadId, claimed) =>
+    set((state) =>
+      state.claimedThreadIds[threadId] === claimed
+        ? state
+        : {
+            claimedThreadIds: {
+              ...state.claimedThreadIds,
+              [threadId]: claimed,
+            },
+          },
+    ),
+  setFollowing: (
+    runId,
+    following,
+    connection = following ? "connected" : "idle",
+  ) =>
+    set((state) => {
+      const session = state.sessions[runId];
+      if (!session) return state;
+      if (
+        session.following === following &&
+        session.connection === connection
+      ) {
+        return state;
+      }
+      return {
+        sessions: {
+          ...state.sessions,
+          [runId]: { ...session, following, connection },
+        },
+      };
+    }),
+  setConnectionError: (runId, error) =>
+    set((state) => {
+      const session = state.sessions[runId];
+      if (!session) return state;
+      return {
+        sessions: {
+          ...state.sessions,
+          [runId]: {
+            ...session,
+            error,
+            connection: error ? "disconnected" : session.connection,
+          },
+        },
+      };
+    }),
+  openPanel: (openRunId) => set({ openRunId }),
+  closePanel: () => set({ openRunId: null }),
+  setActivityOpen: (runId, activityId, open) =>
+    set((state) => {
+      const current = state.activityOpenByRunId[runId] ?? {};
+      if (current[activityId] === open) return state;
+      return {
+        activityOpenByRunId: {
+          ...state.activityOpenByRunId,
+          [runId]: { ...current, [activityId]: open },
+        },
+      };
+    }),
+  setPlanReviewOpen: (runId, open) =>
+    set((state) => {
+      const current = state.planReviewByRunId[runId];
+      if (!current || current.open === open) return state;
+      return {
+        planReviewByRunId: {
+          ...state.planReviewByRunId,
+          [runId]: { ...current, open },
+        },
+      };
+    }),
+  setPlanReviewEditing: (runId, editing) =>
+    set((state) => {
+      const current = state.planReviewByRunId[runId];
+      if (!current || current.editing === editing) return state;
+      return {
+        planReviewByRunId: {
+          ...state.planReviewByRunId,
+          [runId]: { ...current, editing },
+        },
+      };
+    }),
+  setPlanReviewDraft: (runId, draft) =>
+    set((state) => {
+      const current = state.planReviewByRunId[runId];
+      if (!current || current.draft === draft) return state;
+      return {
+        planReviewByRunId: {
+          ...state.planReviewByRunId,
+          [runId]: { ...current, draft },
+        },
+      };
+    }),
+}));
+
+const ownedFollowers = new Map<string, AbortController>();
+const externalFollowerStops = new Map<string, Set<() => void>>();
+const pendingStreamEvents = new Map<
+  string,
+  {
+    run: ResearchRun;
+    event: ResearchEvent;
+    timer: ReturnType<typeof setTimeout>;
+  }
+>();
+const STREAM_EVENT_FLUSH_MS = 80;
+
+function flushPendingStreamEvent(runId: string): void {
+  const pending = pendingStreamEvents.get(runId);
+  if (!pending) return;
+  clearTimeout(pending.timer);
+  pendingStreamEvents.delete(runId);
+  useResearchRunStore.getState().ingest(pending.run, pending.event);
+}
+
+function canCoalesceStreamEvent(
+  previous: ResearchEvent,
+  next: ResearchEvent,
+): boolean {
+  if (previous.event !== next.event) return false;
+  if (next.event === "report.updated") return true;
+  return (
+    next.event === "reasoning.updated" &&
+    previous.data.callId === next.data.callId &&
+    (previous.data.attempt ?? 0) === (next.data.attempt ?? 0)
+  );
+}
+
+function compactReplayUpdates(
+  updates: ResearchRunUpdate[],
+): ResearchRunUpdate[] {
+  const compacted: ResearchRunUpdate[] = [];
+  for (const update of updates) {
+    const event = update.event;
+    const previous = compacted[compacted.length - 1];
+    if (
+      event &&
+      previous?.event &&
+      canCoalesceStreamEvent(previous.event, event)
+    ) {
+      const reasoningDelta =
+        event.event === "reasoning.updated"
+          ? `${previous.event.data.reasoningDelta ?? ""}${event.data.reasoningDelta ?? ""}`
+          : undefined;
+      compacted[compacted.length - 1] = {
+        ...update,
+        event: {
+          ...event,
+          createdAt: previous.event.createdAt,
+          data: {
+            ...previous.event.data,
+            ...event.data,
+            ...(reasoningDelta !== undefined ? { reasoningDelta } : {}),
+          },
+        },
+      };
+    } else {
+      compacted.push(update);
+    }
+  }
+  return compacted;
+}
+
+function hydrateResearchReplay(
+  runId: string,
+  updates: ResearchRunUpdate[],
+  connection?: ResearchConnectionState,
+): void {
+  if (!updates.length) return;
+  useResearchRunStore.setState((state) => {
+    const previous = state.sessions[runId];
+    if (!previous) return state;
+    const compacted = compactReplayUpdates(
+      updates.filter(
+        (update) => update.event && update.event.id > previous.lastAppliedSeq,
+      ),
+    );
+    let activities = previous.activities;
+    let lastAppliedSeq = previous.lastAppliedSeq;
+    let run = previous.run;
+    for (const update of compacted) {
+      if (!update.event || update.event.id <= lastAppliedSeq) continue;
+      activities = reduceActivity(activities, update.event);
+      lastAppliedSeq = update.event.id;
+      if (
+        update.run.lastEventSeq > run.lastEventSeq ||
+        (update.run.lastEventSeq === run.lastEventSeq &&
+          update.run.updatedAt >= run.updatedAt)
+      ) {
+        run = update.run;
+      }
+    }
+    if (lastAppliedSeq === previous.lastAppliedSeq) return state;
+    const planReview = syncPlanReviewState(
+      state.planReviewByRunId[runId],
+      run,
+    );
+    const settled = isSettledResearchRun(run, lastAppliedSeq);
+    return {
+      sessions: {
+        ...state.sessions,
+        [runId]: {
+          ...previous,
+          run,
+          activities,
+          lastAppliedSeq,
+          following: settled ? false : previous.following,
+          connection: settled ? "idle" : (connection ?? previous.connection),
+          error: settled ? null : previous.error,
+        },
+      },
+      ...(planReview && planReview !== state.planReviewByRunId[runId]
+        ? {
+            planReviewByRunId: {
+              ...state.planReviewByRunId,
+              [runId]: planReview,
+            },
+          }
+        : {}),
+    };
+  });
+}
+
+export function ingestResearchUpdate(
+  run: ResearchRun,
+  event?: ResearchEvent,
+): void {
+  if (!event) {
+    flushPendingStreamEvent(run.id);
+    useResearchRunStore.getState().ingest(run);
+    return;
+  }
+  if (event.event !== "reasoning.updated" && event.event !== "report.updated") {
+    flushPendingStreamEvent(run.id);
+    useResearchRunStore.getState().ingest(run, event);
+    return;
+  }
+
+  const pending = pendingStreamEvents.get(run.id);
+  if (pending && canCoalesceStreamEvent(pending.event, event)) {
+    const reasoningDelta =
+      event.event === "reasoning.updated"
+        ? `${pending.event.data.reasoningDelta ?? ""}${event.data.reasoningDelta ?? ""}`
+        : undefined;
+    pendingStreamEvents.set(run.id, {
+      run,
+      event: {
+        ...event,
+        createdAt: pending.event.createdAt,
+        data: {
+          ...pending.event.data,
+          ...event.data,
+          ...(reasoningDelta !== undefined ? { reasoningDelta } : {}),
+        },
+      },
+      timer: pending.timer,
+    });
+    return;
+  }
+  flushPendingStreamEvent(run.id);
+  pendingStreamEvents.set(run.id, {
+    run,
+    event,
+    timer: setTimeout(
+      () => flushPendingStreamEvent(run.id),
+      STREAM_EVENT_FLUSH_MS,
+    ),
+  });
+}
+
+export function beginExternalResearchFollow(
+  run: ResearchRun,
+  stop: () => void,
+): () => void {
+  ingestResearchUpdate(run);
+  useResearchRunStore.getState().openPanel(run.id);
+  useResearchRunStore.getState().setConnectionError(run.id, null);
+  useResearchRunStore.getState().setFollowing(run.id, true, "connected");
+  const stops = externalFollowerStops.get(run.id) ?? new Set();
+  stops.add(stop);
+  externalFollowerStops.set(run.id, stops);
+  return () => {
+    const currentStops = externalFollowerStops.get(run.id);
+    currentStops?.delete(stop);
+    if (currentStops?.size === 0) externalFollowerStops.delete(run.id);
+    flushPendingStreamEvent(run.id);
+    const latest = useResearchRunStore.getState().sessions[run.id]?.run;
+    useResearchRunStore
+      .getState()
+      .setFollowing(
+        run.id,
+        false,
+        terminalStatuses.has(latest?.status ?? "") ? "idle" : "disconnected",
+      );
+  };
+}
+
+export function ensureResearchRunFollowed(
+  runId: string,
+  initialRun?: ResearchRun,
+): void {
+  if (initialRun) ingestResearchUpdate(initialRun);
+  const state = useResearchRunStore.getState();
+  const session = state.sessions[runId];
+  if (
+    session &&
+    isSettledResearchRun(session.run, session.lastAppliedSeq)
+  ) {
+    state.setConnectionError(runId, null);
+    state.setFollowing(runId, false, "idle");
+    return;
+  }
+  if (session?.error) return;
+  if (state.sessions[runId]?.following || ownedFollowers.has(runId)) return;
+  const controller = new AbortController();
+  ownedFollowers.set(runId, controller);
+  state.setFollowing(runId, true, "connecting");
+  void (async () => {
+    let replayThroughSeq = 0;
+    let replaying = true;
+    const replayUpdates: ResearchRunUpdate[] = [];
+    const flushReplay = (markConnected = true) => {
+      if (replayUpdates.length) {
+        hydrateResearchReplay(
+          runId,
+          replayUpdates.splice(0),
+          markConnected ? "connected" : undefined,
+        );
+      }
+      replaying = false;
+      if (markConnected) {
+        useResearchRunStore.getState().setFollowing(runId, true, "connected");
+      }
+    };
+    try {
+      for await (const update of followResearchRun(runId, {
+        initialRun,
+        signal: controller.signal,
+        replayFrom: session?.lastAppliedSeq ?? 0,
+      })) {
+        if (update.source === "snapshot") {
+          const appliedSeq =
+            useResearchRunStore.getState().sessions[runId]?.lastAppliedSeq ?? 0;
+          if (!replaying && update.run.lastEventSeq > appliedSeq) {
+            replaying = true;
+            useResearchRunStore
+              .getState()
+              .setFollowing(runId, true, "reconnecting");
+          }
+          replayThroughSeq = Math.max(
+            replayThroughSeq,
+            update.run.lastEventSeq,
+          );
+          ingestResearchUpdate(update.run);
+          if (replayThroughSeq === 0) flushReplay();
+          continue;
+        }
+        if (replaying && update.event && update.event.id <= replayThroughSeq) {
+          replayUpdates.push(update);
+          if (update.event.id >= replayThroughSeq) flushReplay();
+          continue;
+        }
+        if (replaying) flushReplay();
+        ingestResearchUpdate(update.run, update.event);
+        useResearchRunStore.getState().setFollowing(runId, true, "connected");
+      }
+      if (replaying) flushReplay();
+      useResearchRunStore.getState().setConnectionError(runId, null);
+    } catch (error) {
+      if (!controller.signal.aborted) {
+        useResearchRunStore
+          .getState()
+          .setConnectionError(
+            runId,
+            error instanceof Error
+              ? error.message
+              : "Research activity disconnected",
+          );
+      }
+    } finally {
+      if (replaying) flushReplay(false);
+      flushPendingStreamEvent(runId);
+      const stillOwnsFollow = ownedFollowers.get(runId) === controller;
+      if (stillOwnsFollow)
+        ownedFollowers.delete(runId);
+      if (stillOwnsFollow) {
+        const run = useResearchRunStore.getState().sessions[runId]?.run;
+        useResearchRunStore
+          .getState()
+          .setFollowing(
+            runId,
+            false,
+            terminalStatuses.has(run?.status ?? "") ? "idle" : "disconnected",
+          );
+      }
+    }
+  })();
+}
+
+export function stopResearchRunFollower(runId: string): void {
+  flushPendingStreamEvent(runId);
+  ownedFollowers.get(runId)?.abort();
+  ownedFollowers.delete(runId);
+}
+
+export function resetResearchRunState(): void {
+  for (const controller of ownedFollowers.values()) controller.abort();
+  ownedFollowers.clear();
+  for (const stops of externalFollowerStops.values()) {
+    for (const stop of stops) stop();
+  }
+  externalFollowerStops.clear();
+  for (const pending of pendingStreamEvents.values()) clearTimeout(pending.timer);
+  pendingStreamEvents.clear();
+  useResearchRunStore.setState({
+    sessions: {},
+    latestRunByThreadId: {},
+    claimedThreadIds: {},
+    activityOpenByRunId: {},
+    planReviewByRunId: {},
+    openRunId: null,
+  });
+}
+
+if (typeof window !== "undefined") {
+  window.addEventListener(AUTH_SESSION_CLEARED_EVENT, resetResearchRunState);
+}

studio/frontend/src/features/chat/types/research.ts

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export type ResearchRunStatus =
+  | "planning"
+  | "awaiting_approval"
+  | "queued"
+  | "running"
+  | "paused"
+  | "cancelling"
+  | "cancelled"
+  | "completed"
+  | "failed";
+
+export type ResearchPhase = "planning" | "decision" | "synthesis" | "unknown";
+export type ResearchAction = "search" | "fetch";
+
+export interface ResearchPlanStep {
+  title: string;
+  query: string;
+}
+
+export interface ResearchPlan {
+  title: string;
+  steps: ResearchPlanStep[];
+}
+
+export interface ResearchEvidenceSource {
+  kind: "knowledge_base";
+  chunkId?: string | null;
+  documentId?: string | null;
+  filename: string;
+  page?: number | null;
+  score?: number | null;
+  snippet?: string;
+}
+
+export interface ResearchStepResult {
+  action?: ResearchAction;
+  input?: string;
+  sourceCount?: number;
+  sourceUrls?: string[];
+  evidenceSources?: ResearchEvidenceSource[];
+  excerpt?: string;
+  error?: string;
+}
+
+export interface ResearchStepSnapshot extends ResearchPlanStep {
+  position: number;
+  input?: string;
+  status: "pending" | "queued" | "running" | "completed" | "failed";
+  result?: ResearchStepResult | null;
+  startedAt?: number | null;
+  completedAt?: number | null;
+}
+
+export interface ResearchSource {
+  id?: string | number;
+  stepPosition?: number | null;
+  title: string;
+  url: string;
+  snippet?: string | null;
+  fetchedAt?: number;
+}
+
+export interface ResearchInferenceRequest {
+  model: string;
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  enableThinking?: boolean;
+  reasoningEffort?: string;
+}
+
+export interface ResearchBudgets {
+  maxSteps: number;
+  maxSources: number;
+  modelTimeoutSeconds: number;
+  toolTimeoutSeconds: number;
+}
+
+export interface ResearchWebsitePolicy {
+  allowedDomains: string[];
+  blockedDomains: string[];
+}
+
+export interface CreateResearchRunInput {
+  threadId: string;
+  userMessageId: string;
+  assistantMessageId?: string;
+  inferenceRequest: ResearchInferenceRequest;
+  ragScope?: Record<string, unknown>;
+  budgets?: Partial<ResearchBudgets>;
+  websitePolicy?: ResearchWebsitePolicy;
+}
+
+export interface ResearchRun {
+  id: string;
+  threadId: string;
+  userMessageId: string;
+  assistantMessageId?: string | null;
+  status: ResearchRunStatus;
+  plan: ResearchPlan | null;
+  planRevision: number;
+  planHash: string | null;
+  steps: ResearchStepSnapshot[];
+  sources: ResearchSource[];
+  config?: {
+    model?: string;
+    inferenceRequest?: Record<string, unknown>;
+    ragScope?: Record<string, unknown> | null;
+    budgets?: ResearchBudgets;
+    websitePolicy?: ResearchWebsitePolicy;
+  };
+  cancelRequested?: boolean;
+  retryCount?: number;
+  error?: string | null;
+  report?: string | null;
+  lastEventSeq: number;
+  createdAt: number;
+  updatedAt: number;
+  startedAt?: number | null;
+  completedAt?: number | null;
+  heartbeatAt?: number | null;
+}
+
+export type ResearchEventType =
+  | "run.created"
+  | "run.started"
+  | "plan.ready"
+  | "run.approved"
+  | "reasoning.updated"
+  | "step.started"
+  | "source.added"
+  | "step.completed"
+  | "step.failed"
+  | "report.updated"
+  | "run.cancelRequested"
+  | "run.cancelled"
+  | "run.retried"
+  | "run.completed"
+  | "run.failed";
+
+export interface ResearchEventData {
+  run: ResearchRun;
+  createdAt: number;
+  attempt?: number;
+  status?: ResearchRunStatus;
+  phase?: ResearchPhase;
+  callId?: string;
+  reasoningDelta?: string;
+  reasoningOffset?: number;
+  position?: number;
+  stepPosition?: number;
+  title?: string;
+  action?: ResearchAction;
+  input?: string;
+  url?: string;
+  snippet?: string;
+  fetchedAt?: number;
+  sourceCount?: number;
+  error?: string | null;
+  delta?: string;
+  offset?: number;
+  length?: number;
+  report?: string;
+  plan?: ResearchPlan;
+  planRevision?: number;
+  planHash?: string;
+}
+
+export interface ResearchEvent {
+  id: number;
+  event: ResearchEventType;
+  createdAt: number;
+  data: ResearchEventData;
+  run: ResearchRun;
+}
+
+export interface ResearchMessageMetadata {
+  researchRunId?: string;
+  researchRun?: ResearchRun;
+  researchStatus?: ResearchRunStatus;
+  researchPlanRevision?: number;
+  serverManaged?: boolean;
+  serverRevision?: number;
+  reasoningDuration?: number;
+}

tests/studio/test_deep_research_frontend_contract.py

@@ -0,0 +1,207 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+FRONTEND = ROOT / "studio" / "frontend" / "src"
+
+
+def source(path: str) -> str:
+    return (FRONTEND / path).read_text(encoding="utf-8")
+
+
+def test_research_api_is_isolated_and_cursor_based() -> None:
+    api = source("features/chat/api/research-api.ts")
+    assert 'authFetch("/api/chat/research-runs"' in api
+    assert 'authFetch(`/api/chat/research-runs/active?${query}`)' in api
+    assert "const { runs, hasRun }" in api
+    assert "runs.at(-1) ?? null" in api
+    assert "getResearchThreadState" in api
+    assert "/events?after=${Math.max(0, after)}" in api
+    assert 'headers: { accept: "text/event-stream" }' in api
+    assert "export async function* followResearchRun" in api
+    assert "Math.min(8_000, 500 * 2 ** (failures - 1))" in api
+    assert "for await (const event of streamResearchEvents" in api
+    assert 'source: "event"' in api
+    assert "fresh.report !== run.report" in api
+    assert "await waitForReconnect(" in api
+    assert "while (!(run || signal?.aborted))" in api
+    assert "isPermanentResearchError(error)" in api
+    assert 'yield { run, source: "snapshot" }' in api
+    for action in ("cancel", "retry"):
+        assert f'mutate(id, "{action}")' in api
+    assert 'mutate(id, "approve", { planRevision, planHash })' in api
+    assert "JSON.stringify({ plan, expectedRevision })" in api
+
+
+def test_research_mode_is_single_chat_and_detaches_without_cancel() -> None:
+    adapter = source("features/chat/api/chat-adapter.ts")
+    assert "runtime.deepResearchEnabled" in adapter
+    assert "!options.pairId" in adapter
+    assert 'options.modelType === "base"' in adapter
+    assert "cancelResearchRun(run.id)" not in adapter
+    assert "createResearchRun" in adapter
+    assert "await saveStoredChatMessage({" in adapter
+    assert "unstable_assistantMessageId," in adapter
+    assert "if (!unstable_assistantMessageId)" in adapter
+    assert "assistantMessageId: unstable_assistantMessageId" in adapter
+    assert "followResearchRun(createdRun.id" in adapter
+    assert "inferenceRequest" in adapter
+    assert "Number.isFinite(params.temperature)" in adapter
+    assert "Number.isFinite(params.topP)" in adapter
+    assert "Number.isFinite(params.maxTokens)" in adapter
+    assert "Math.min(8192, Math.floor(params.maxTokens))" in adapter
+    assert 'update.event?.event === "report.updated"' in adapter
+    assert 'update.event?.event === "reasoning.updated"' in adapter
+    assert "The activity store coalesces these high-frequency events" in adapter
+    assert '{ type: "text" as const, text: report }' in adapter
+    assert "if (abortSignal.aborted) return" in adapter
+    assert "await autoLoadSmallestModel()" in adapter
+    assert "signal: researchFollowController.signal" in adapter
+    assert "beginExternalResearchFollow(" in adapter
+    assert "ragScope" in adapter
+    create_block = adapter.split("createdRun = await createResearchRun({", 1)[1].split("});", 1)[0]
+    assert "modelId:" not in create_block
+    assert "prompt," not in create_block
+
+
+def test_research_metadata_and_server_merge_are_persisted() -> None:
+    adapter = source("features/chat/api/chat-adapter.ts")
+    runtime = source("features/chat/runtime-provider.tsx")
+    assert "researchRunId: run.id" in adapter
+    assert "serverManaged: true" in adapter
+    assert "getResearchThreadState(remoteId)" in runtime
+    assert "preserveServerManaged" in runtime
+    assert "sameResearchRun" in runtime
+    assert "existingRevision > incomingRevision" in runtime
+    assert "const userMessage = [...messages]" in runtime
+    assert '.find((message) => message.role === "user")' in runtime
+    assert "pendingRunStartReadyByMessageId.get(userMessage.id)" in runtime
+
+
+def test_research_presentation_is_integrated() -> None:
+    thread = source("components/assistant-ui/thread.tsx")
+    page = source("features/chat/chat-page.tsx")
+    chat_index = source("features/chat/index.ts")
+    store = source("features/chat/stores/chat-runtime-store.ts")
+    activity = source("features/chat/components/research-activity-panel.tsx")
+    message = source("features/chat/components/research-message.tsx")
+    coordinator = source("features/chat/stores/research-run-store.ts")
+    assert "DeepResearchComposerButton" in thread
+    assert "Deep research" in thread
+    research_gate = thread.split("const researchDisabled =", 1)[1].split(";", 1)[0]
+    assert "!modelLoaded" not in research_gate
+    assert "<ResearchMessage />" in thread
+    assert "ResearchActivityPanel" in page
+    assert "ResearchActivitySheet" in page
+    assert "ResearchActivityPanel" in chat_index
+    assert "role=\"log\"" in activity
+    assert "Review the research plan" in activity
+    assert "Start research" in activity
+    assert "cancelResearchRun" in thread
+    assert "Stop research" not in activity
+    assert "retryResearchRun" in activity
+    assert "Deep research completed" in message
+    assert "ensureResearchRunFollowed" in coordinator
+    assert "reasoning.updated" in coordinator
+    assert "source.added" in coordinator
+    assert 'activity.state === "running"' in coordinator
+    assert "terminalState" in coordinator
+    assert 'event.event === "run.completed"' in coordinator
+    assert "compactReplayUpdates" in coordinator
+    assert "hydrateResearchReplay" in coordinator
+    assert "replayThroughSeq" in coordinator
+    assert "needsCatchup" in source("features/chat/api/research-api.ts")
+    assert "Restoring research activity" in activity
+    assert "useLayoutEffect" in activity
+    assert "CollapsibleTrigger" in activity
+    assert "activity.sources?.map" in activity
+    assert "activityOpenByRunId" in coordinator
+    assert "initializeActivityOpenState" not in coordinator
+    assert "setActivityOpen(runId, activity.id, nextOpen)" in activity
+    assert "open={open}" in activity
+    assert "planReviewByRunId" in coordinator
+    assert "setPlanReviewDraft" in coordinator
+    assert "useResearchActivityScroll" in activity
+    assert "MutationObserver" in activity
+    assert "[overflow-anchor:none]" in activity
+    assert "behavior: \"smooth\"" not in activity
+    assert "collapsible={showArtifactPanel}" in page
+    assert "!artifactLayoutActive &&" in page
+    assert '? "30%"' in page
+    assert '? "58%"' in page
+    assert "key={openResearchRunId}" in page
+    assert "effectiveDeepResearchEnabled ||" in thread
+    assert "replayFrom: session?.lastAppliedSeq ?? 0" in coordinator
+    assert "loadBool(CHAT_DEEP_RESEARCH_ENABLED_KEY, false)" in store
+
+
+def test_research_plan_and_status_contract() -> None:
+    types = source("features/chat/types/research.ts")
+    assert '| "queued"' in types
+    assert '| "cancelling"' in types
+    assert "title: string;" in types
+    assert "query: string;" in types
+    assert "position: number;" in types
+    assert "createdAt: number;" in types
+    assert "planRevision: number;" in types
+    assert "planHash: string | null;" in types
+
+
+def test_research_website_limits_are_configurable_and_sent_with_each_run() -> None:
+    component = source("features/chat/components/deep-research-composer-button.tsx")
+    thread = source("components/assistant-ui/thread.tsx")
+    store = source("features/chat/stores/chat-runtime-store.ts")
+    adapter = source("features/chat/api/chat-adapter.ts")
+
+    assert 'label="Allow only"' in component
+    assert 'label="Always block"' in component
+    assert "their subdomains" in component
+    assert ">Websites</span>" in component
+    assert "DeepResearchWebsiteAccessDialog" in thread
+    assert "researchWebsitePolicy" in store
+    assert "CHAT_DEEP_RESEARCH_WEBSITE_POLICY_KEY" in store
+    assert "websitePolicy:" in adapter
+    assert "allowedDomains" in adapter and "blockedDomains" in adapter
+
+
+def test_research_is_one_shot_per_thread_without_disabling_normal_chat() -> None:
+    adapter = source("features/chat/api/chat-adapter.ts")
+    runtime = source("features/chat/runtime-provider.tsx")
+    thread = source("components/assistant-ui/thread.tsx")
+    coordinator = source("features/chat/stores/research-run-store.ts")
+
+    assert "claimedThreadIds" in coordinator
+    assert "setThreadClaimed" in coordinator
+    assert "researchThreadState.hasRun" in runtime
+    assert "threadAlreadyResearched" in adapter
+    assert "runtime.setDeepResearchEnabled(false)" in adapter
+    assert "effectiveDeepResearchEnabled" in thread
+    assert "researchAvailable={!researchUsed}" in thread
+    assert "{researchAvailable ? (" in thread
+    assert "setToolsEnabled" in thread
+    assert "Web search" in thread
+
+
+def test_settled_terminal_research_never_stays_disconnected() -> None:
+    coordinator = source("features/chat/stores/research-run-store.ts")
+    activity = source("features/chat/components/research-activity-panel.tsx")
+
+    assert "function isSettledResearchRun" in coordinator
+    assert 'connection: settled ? "idle"' in coordinator
+    assert "error: settled ? null" in coordinator
+    assert 'state.setFollowing(runId, false, "idle")' in coordinator
+    assert "!isSettledResearchRun(run, session.lastAppliedSeq)" in activity
+
+
+def test_research_stop_is_prompt_only_and_deduplicated() -> None:
+    adapter = source("features/chat/api/chat-adapter.ts")
+    thread = source("components/assistant-ui/thread.tsx")
+    activity = source("features/chat/components/research-activity-panel.tsx")
+
+    assert "stoppingResearchRunIdRef" in thread
+    assert 'activeResearchRun.status === "cancelling"' in thread
+    assert 'aria-label={researchStopping ? "Stopping research"' in thread
+    assert "cancelResearchRun" not in activity
+    assert "Stop research" not in activity
+    assert "abortSignal.reason as { detach?: boolean }" in adapter
+    assert "await cancelResearchRun(createdRun.id)" in adapter