Skip to content

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

Studio: let Deep Research write longer reports on saved connections (#10254)

Nilayec0cb885f933
diff --git a/studio/backend/core/research_runs.py b/studio/backend/core/research_runs.py
index 6e09d05a4fb..be3085db00c 100644
--- a/studio/backend/core/research_runs.py
+++ b/studio/backend/core/research_runs.py
@@ -11,6 +11,7 @@ import os
import re
import sqlite3
import threading
+import time
import uuid
from contextlib import asynccontextmanager
from datetime import datetime, timedelta, timezone
@@ -55,6 +56,7 @@ from core.research.prompts import (
_system_prompt_with_instructions,
)
from loggers import get_logger
+from storage import providers_db
from storage import research_runs_db as db
from storage.studio_db import (
get_chat_message,
@@ -87,6 +89,23 @@ _MIN_SYNTHESIS_EVIDENCE_CHARS = 1_500
_MIN_QUESTION_CHARS = 800
_SYNTHESIS_EVIDENCE_CHARS_PER_TOKEN = 3.0
_SYNTHESIS_CONTEXT_RESERVE_TOKENS = 4_096
+_SYNTHESIS_MAX_TOKENS = 16_384
+# Nothing between here and the provider bounds what is sent, and published caps reach 384_000.
+_SYNTHESIS_MAX_TOKENS_CEILING = 65_536
+# Deliberately pessimistic: overshooting the wall clock loses the run, undershooting shortens it.
+_SYNTHESIS_TOKENS_PER_SECOND = 50
+_CAP_UNREADABLE = object()
+_CAP_LOOKUP_ATTEMPTS = 3
+_CAP_LOOKUP_RETRY_SECONDS = 0.2
+_PROGRESS_FLUSH_CHARS = 512
+_PROGRESS_FLUSH_SECONDS = 0.25
+# _PROGRESS_FLUSH_CHARS / _PROGRESS_FLUSH_SECONDS * 64: both arms must scale from the same
+# written length, or the time arm's knee lands where a 65_536-token report ENDS and only it binds.
+_PROGRESS_FLUSH_CHARS_PER_SECOND = 131_072
+# Providers whose thinking answers truncate below a floor; mirrors
+# EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER in the same client module.
+_EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER = {"kimi": 16_000}
+_EXTERNAL_MIN_OUTPUT_TOKENS = 64
# Below this loaded context the prompt scaffolding alone fills the window, so grounding is skipped.
_AUTO_SCRAPE_MIN_CONTEXT_TOKENS = 8_192
# OFF by default (UNSLOTH_RESEARCH_AUTO_SCRAPE=1): benchmarking showed no reliable accuracy gain
@@ -412,10 +431,103 @@ def _clamp_max_tokens_for_context(
def _resolve_max_tokens(
max_tokens: int | None, inference: dict[str, Any], messages: list[dict]
) -> int:
- requested = int(max_tokens or inference.get("maxTokens") or 4096)
- ceiling = 16384 if max_tokens is not None else 8192
- capped = min(requested, ceiling)
- return _clamp_max_tokens_for_context(capped, messages, inference = inference)
+ if max_tokens is None:
+ requested = min(int(inference.get("maxTokens") or 4096), 8192)
+ else:
+ # Re-capping a budget the caller already resolved is what truncated the report.
+ requested = max(1, int(max_tokens))
+ # Defers rather than short-circuits: _loaded_context_length is already None for a run
+ # carrying a providerType.
+ return _clamp_max_tokens_for_context(requested, messages, inference = inference)
+
+
+def _synthesis_max_tokens(inference: dict[str, Any], model_timeout_seconds: Any = None) -> int:
+ """The report's output budget, between `_report_floor` and `_synthesis_budget_ceiling`.
+
+ The client's ceiling is a limit the provider PUBLISHES, not one any request has survived.
+ """
+ if not inference.get("providerType"):
+ return _SYNTHESIS_MAX_TOKENS
+ floor = _provider_output_floor(inference.get("providerType"))
+ saved = _saved_connection_cap(inference.get("providerId"))
+ if saved is _CAP_UNREADABLE:
+ # Neither signal is confirmable, so spend the smaller: losing a finished run to a
+ # transient lock costs far more.
+ unconfirmed = _positive_int_or_none(inference.get("maxOutputTokens"))
+ return max(min(unconfirmed or _SYNTHESIS_MAX_TOKENS, _SYNTHESIS_MAX_TOKENS), floor)
+ resolved = _positive_int_or_none(inference.get("maxOutputTokens"))
+ if resolved and not saved and inference.get("maxOutputTokensFromSavedCap") is True:
+ # The cap was the only thing holding this number up, and clearing it is what that
+ # field is FOR on an undocumented model.
+ resolved = None
+ if resolved:
+ # The run is durable, so the cap can have been lowered since the client resolved this.
+ budget = min(resolved, saved) if saved else resolved
+ else:
+ # Legacy run: the saved cap is connection-wide, so raising on it would be a guess.
+ budget = _SYNTHESIS_MAX_TOKENS
+ # Below its provider floor a thinking answer is cut off before the report starts.
+ return max(
+ min(budget, _synthesis_budget_ceiling(model_timeout_seconds)),
+ _report_floor(inference),
+ floor,
+ )
+
+
+def _report_floor(inference: dict[str, Any]) -> int:
+ """The budget every run had before a connection ceiling was read at all.
+
+ Only a model's own published limit may go below it, never an override sizing the chat
+ slider -- and `maxOutputTokens` arrives with the override already folded in.
+ """
+ published = _positive_int_or_none(inference.get("maxOutputTokensPublished"))
+ if published:
+ return min(_SYNTHESIS_MAX_TOKENS, published)
+ return _SYNTHESIS_MAX_TOKENS
+
+
+def _synthesis_budget_ceiling(model_timeout_seconds: Any = None) -> int:
+ """The most this run can usefully ask for, never below the previous default.
+
+ `_stream_completion` aborts at `modelTimeoutSeconds` WITHOUT returning the report it has
+ already streamed, while running out of budget merely truncates it under a notice.
+ """
+ ceiling = _SYNTHESIS_MAX_TOKENS_CEILING
+ timeout = model_timeout_seconds
+ if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+ timeout = None
+ # 0 is "unlimited" in the budgets schema.
+ if timeout and timeout > 0:
+ ceiling = min(ceiling, int(timeout * _SYNTHESIS_TOKENS_PER_SECOND))
+ return max(ceiling, _SYNTHESIS_MAX_TOKENS)
+
+
+def _provider_output_floor(provider_type: object) -> int:
+ if not isinstance(provider_type, str):
+ return _EXTERNAL_MIN_OUTPUT_TOKENS
+ return _EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER.get(provider_type, _EXTERNAL_MIN_OUTPUT_TOKENS)
+
+
+def _saved_connection_cap(provider_id: object) -> int | None | object:
+ """The connection's saved Max Output Tokens, None if it has none, else _CAP_UNREADABLE.
+
+ An unreadable row is not an uncapped connection: the cap may have been lowered since this
+ durable run was created, and spending the older ceiling is the request the user capped away.
+ """
+ if not isinstance(provider_id, str):
+ return None
+ for attempt in range(_CAP_LOOKUP_ATTEMPTS):
+ try:
+ provider = providers_db.get_provider(provider_id) or {}
+ except Exception:
+ logger.debug("research.provider_cap_probe_failed", exc_info = True)
+ # A read that lost the writer lock is transient, and this runs off the loop.
+ if attempt + 1 < _CAP_LOOKUP_ATTEMPTS:
+ time.sleep(_CAP_LOOKUP_RETRY_SECONDS)
+ continue
+ return _CAP_UNREADABLE
+ return _positive_int_or_none(provider.get("max_output_tokens"))
+ return _CAP_UNREADABLE
def _normalize_completion_usage(raw: Any) -> dict[str, int] | None:
@@ -1536,6 +1648,19 @@ class ResearchSupervisor:
attempt = 0
try:
while True:
+ if (
+ max_tokens is not None
+ and inference.get("providerType")
+ and phase in ("synthesis", "synthesis_recovery")
+ ):
+ # This loop re-sends after a queue or rate-limit wait, so recovery
+ # and every retry are bounded by the cap in force when they go out.
+ max_tokens = min(
+ max_tokens,
+ await asyncio.to_thread(
+ _synthesis_max_tokens, inference, model_timeout
+ ),
+ )
payload["max_tokens"] = _resolve_max_tokens(
max_tokens,
inference,
@@ -1690,10 +1815,17 @@ class ResearchSupervisor:
run["id"], phase, call_id, report, emitted_labels
)
pending_chars = len(pending_reasoning) + len(pending_report)
+ # Every flush rewrites the whole row: quadratic in report length.
+ written = len(report) + len(reasoning)
+ flush_chars = max(_PROGRESS_FLUSH_CHARS, written // 64)
+ flush_seconds = max(
+ _PROGRESS_FLUSH_SECONDS, written / _PROGRESS_FLUSH_CHARS_PER_SECOND
+ )
if (
- pending_chars >= 512
+ pending_chars >= flush_chars
or pending_chars > 0
- and asyncio.get_running_loop().time() - last_progress_flush >= 0.25
+ and asyncio.get_running_loop().time() - last_progress_flush
+ >= flush_seconds
):
await flush_progress()
if semantic_output_at is None:
@@ -2582,17 +2714,49 @@ class ResearchSupervisor:
),
},
]
- (
- report,
- synthesis_reasoning,
- synthesis_finish_reason,
- synthesis_usage,
- ) = await self._stream_completion(
- run,
- synthesis_messages,
- phase = "synthesis",
- max_tokens = 16384,
+ synthesis_max_tokens = await asyncio.to_thread(
+ _synthesis_max_tokens,
+ run["config"].get("inferenceRequest") or {},
+ (run["config"].get("budgets") or {}).get("modelTimeoutSeconds"),
)
+ try:
+ (
+ report,
+ synthesis_reasoning,
+ synthesis_finish_reason,
+ synthesis_usage,
+ ) = await self._stream_completion(
+ run,
+ synthesis_messages,
+ phase = "synthesis",
+ max_tokens = synthesis_max_tokens,
+ )
+ except (RunCancelled, LeaseLost, httpx.ReadTimeout):
+ raise
+ except Exception:
+ if synthesis_max_tokens <= _SYNTHESIS_MAX_TOKENS:
+ raise
+ # The ways a connection can refuse a raised budget are not enumerable here, and
+ # failing would discard a run that already finished its research.
+ logger.warning(
+ "research.synthesis_budget_refused run_id=%s budget=%s",
+ run["id"],
+ synthesis_max_tokens,
+ exc_info = True,
+ )
+ await self._check_active(run["id"])
+ synthesis_max_tokens = _SYNTHESIS_MAX_TOKENS
+ (
+ report,
+ synthesis_reasoning,
+ synthesis_finish_reason,
+ synthesis_usage,
+ ) = await self._stream_completion(
+ run,
+ synthesis_messages,
+ phase = "synthesis",
+ max_tokens = synthesis_max_tokens,
+ )
await self._check_active(run["id"])
report = _select_synthesis_report(report, synthesis_reasoning)
truncation_notice = ""
@@ -2627,22 +2791,37 @@ class ResearchSupervisor:
synthesis_messages[1],
]
recovery_max_tokens = _resolve_max_tokens(
- 16384,
+ synthesis_max_tokens,
_run_inference_request(run),
recovery_messages,
)
- (
- recovered_report,
- recovery_reasoning,
- recovery_finish_reason,
- recovery_usage,
- ) = await self._stream_completion(
- run,
- recovery_messages,
- phase = "synthesis_recovery",
- max_tokens = 16384,
- enable_thinking = False,
- )
+ try:
+ (
+ recovered_report,
+ recovery_reasoning,
+ recovery_finish_reason,
+ recovery_usage,
+ ) = await self._stream_completion(
+ run,
+ recovery_messages,
+ phase = "synthesis_recovery",
+ max_tokens = synthesis_max_tokens,
+ enable_thinking = False,
+ )
+ except (RunCancelled, LeaseLost):
+ raise
+ except Exception:
+ # Failing would discard the draft recovery was called to rescue, and its
+ # larger prompt can be refused at a budget the first request fit inside.
+ logger.warning(
+ "research.synthesis_recovery_failed run_id=%s budget=%s",
+ run["id"],
+ synthesis_max_tokens,
+ exc_info = True,
+ )
+ await self._check_active(run["id"])
+ recovered_report, recovery_reasoning = "", ""
+ recovery_finish_reason, recovery_usage = None, None
synthesis_reasoning += recovery_reasoning
recovered = _select_synthesis_report(recovered_report, recovery_reasoning)
# A second attempt at the SAME report under the same budget, not a correction of
@@ -2665,7 +2844,7 @@ class ResearchSupervisor:
synthesis_usage = recovery_usage
else:
requested_max_tokens = _resolve_max_tokens(
- 16384,
+ synthesis_max_tokens,
_run_inference_request(run),
synthesis_messages,
)
diff --git a/studio/backend/routes/research_runs.py b/studio/backend/routes/research_runs.py
index 4350f31e6b1..9a113afe072 100644
--- a/studio/backend/routes/research_runs.py
+++ b/studio/backend/routes/research_runs.py
@@ -22,6 +22,7 @@ from core.inference.message_content import message_text_with_pastes
from core.inference.web_access_policy import normalize_website_policy
from storage import research_runs_db as db
from core.inference.providers import provider_runs_local_tools
+from models.providers import MAX_JSON_SAFE_INTEGER
from storage import providers_db
from storage.studio_db import get_chat_message, get_chat_thread, upsert_chat_message
from utils.current_date_prompt_settings import current_date_prompt_line
@@ -215,6 +216,9 @@ def _sanitize_config(
"temperature",
"topP",
"maxTokens",
+ "maxOutputTokens",
+ "maxOutputTokensFromSavedCap",
+ "maxOutputTokensPublished",
"enableThinking",
"reasoningEffort",
}
@@ -282,6 +286,24 @@ def _sanitize_config(
request["maxTokens"] = int(request["maxTokens"])
if not 1 <= request["maxTokens"] <= 8192:
raise ValueError
+ if "maxOutputTokens" in request:
+ # Strict like the saved-connection schema: bool is an int subclass, and int()
+ # would truncate a float or raise OverflowError, turning a 400 into a 500.
+ budget = request["maxOutputTokens"]
+ if isinstance(budget, bool) or not isinstance(budget, int):
+ raise ValueError
+ if not 1 <= budget <= MAX_JSON_SAFE_INTEGER:
+ raise ValueError
+ if "maxOutputTokensFromSavedCap" in request and not isinstance(
+ request["maxOutputTokensFromSavedCap"], bool
+ ):
+ raise ValueError
+ if "maxOutputTokensPublished" in request:
+ published = request["maxOutputTokensPublished"]
+ if isinstance(published, bool) or not isinstance(published, int):
+ raise ValueError
+ if not 1 <= published <= MAX_JSON_SAFE_INTEGER:
+ raise ValueError
if "enableThinking" in request and not isinstance(request["enableThinking"], bool):
raise ValueError
if "reasoningEffort" in request:
diff --git a/studio/backend/tests/test_research_runs_hardening.py b/studio/backend/tests/test_research_runs_hardening.py
index 761cb12bd87..75de07b8911 100644
--- a/studio/backend/tests/test_research_runs_hardening.py
+++ b/studio/backend/tests/test_research_runs_hardening.py
@@ -8,6 +8,7 @@ from __future__ import annotations
import asyncio
import datetime
import json
+import sqlite3
import sys
import time
from pathlib import Path
@@ -15,6 +16,7 @@ from types import SimpleNamespace
import httpx
import pytest
+from fastapi import HTTPException
from core import research_runs
from core.research.citations import (
@@ -35,6 +37,7 @@ from core.research_runs import (
_estimate_prompt_tokens,
_resolve_max_tokens,
_synthesis_length_limit_error,
+ _synthesis_max_tokens,
)
from routes.research_runs import CreateResearchRun, _is_sensitive_key, _sanitize_config
@@ -326,6 +329,481 @@ def test_a_saved_connection_run_is_not_blamed_on_the_loaded_context(monkeypatch)
assert "output limit" in message
+def test_resolve_max_tokens_honours_a_budget_above_the_old_ceiling(monkeypatch):
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda *a, **k: None)
+ assert _resolve_max_tokens(32_768, {}, [{"role": "user", "content": "x"}]) == 32_768
+
+
+def test_resolve_max_tokens_still_caps_a_thread_setting_at_8192(monkeypatch):
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda *a, **k: None)
+ messages = [{"role": "user", "content": "x"}]
+ assert _resolve_max_tokens(None, {"maxTokens": 100_000}, messages) == 8_192
+ assert _resolve_max_tokens(None, {}, messages) == 4_096
+
+
+def test_a_saved_connection_budget_ignores_the_resident_local_model(monkeypatch):
+ """A connection generates on the provider's hardware; the local window bounds nothing."""
+ # Model _loaded_context_length's contract, not a flat value, or the stub itself clamps.
+ monkeypatch.setattr(
+ research_runs,
+ "_loaded_context_length",
+ lambda _inf = None: None if (_inf or {}).get("providerType") else 8_192,
+ )
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 32_768}
+ messages = [{"role": "user", "content": "x" * 30_000}]
+ assert _resolve_max_tokens(32_768, inference, messages) == 32_768
+
+
+def test_a_local_run_still_clamps_to_the_loaded_context(monkeypatch):
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda _inf = None: 8_192)
+ messages = [{"role": "user", "content": "x" * 30_000}]
+ assert _resolve_max_tokens(16_384, {}, messages) < 16_384
+
+
+def test_a_lowered_connection_cap_bounds_a_stale_client_ceiling(monkeypatch):
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 20_000}
+ )
+ inference = {
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 65_536,
+ }
+ assert _synthesis_max_tokens(inference) == 20_000
+
+
+def test_a_client_ceiling_stands_when_the_connection_has_no_cap(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 65_536}
+ assert _synthesis_max_tokens(inference) == 65_536
+
+
+def test_a_saved_cap_cannot_drop_a_connection_below_its_provider_floor(monkeypatch):
+ """Kimi truncates a thinking answer below 16k, so the chat path never asks for less."""
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 8_000}
+ )
+ inference = {"providerType": "kimi", "providerId": "p1", "maxOutputTokens": 32_768}
+ # The report floor gets there first; the provider floor holds a lower published limit.
+ assert _synthesis_max_tokens(inference) == 16_384
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ published_low = {
+ **inference,
+ "maxOutputTokens": 4_096,
+ "maxOutputTokensPublished": 4_096,
+ }
+ assert _synthesis_max_tokens(published_low) == 16_000
+
+
+def test_a_saved_cap_below_the_previous_default_does_not_shorten_the_report(monkeypatch):
+ """A cap set for chat cost may not shorten a report the user was already getting.
+
+ The override arrives ALREADY FOLDED into maxOutputTokens, so 8_192 here is what the client
+ really sends for a 65_536 model on a connection capped at 8_192, not a hypothetical.
+ """
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 8_192}
+ )
+ inference = {
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 8_192,
+ "maxOutputTokensPublished": 65_536,
+ "maxOutputTokensFromSavedCap": False,
+ }
+ assert _synthesis_max_tokens(inference, 900) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_model_that_genuinely_stops_low_still_lowers_the_report(monkeypatch):
+ """Asking a 4_096-token model for 16_384 is refused, so the floor cannot be blind to it."""
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "openai",
+ "providerId": "p1",
+ "externalModel": "gpt-4-turbo",
+ "maxOutputTokens": 4_096,
+ "maxOutputTokensPublished": 4_096,
+ "maxOutputTokensFromSavedCap": False,
+ }
+ assert _synthesis_max_tokens(inference, 900) == 4_096
+
+
+def test_an_undocumented_model_capped_low_keeps_the_old_floor(monkeypatch):
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 8_000}
+ )
+ inference = {
+ "providerType": "custom",
+ "providerId": "p1",
+ "externalModel": "some-self-hosted-model",
+ "maxOutputTokens": 8_000,
+ "maxOutputTokensFromSavedCap": True,
+ }
+ assert _synthesis_max_tokens(inference, 900) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_cap_between_the_floor_and_the_ceiling_still_binds(monkeypatch):
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 20_000}
+ )
+ inference = {
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 32_768,
+ "maxOutputTokensPublished": 65_536,
+ "maxOutputTokensFromSavedCap": False,
+ }
+ assert _synthesis_max_tokens(inference, 900) == 20_000
+
+
+def test_clearing_the_saved_cap_invalidates_a_ceiling_only_it_grounded(monkeypatch):
+ """Blanking the Max Tokens limit is what that field is FOR on an undocumented model.
+
+ It was the only thing holding the ceiling up, so once cleared this run must stop asking
+ for a number a run created now would not ask for either.
+ """
+ inference = {
+ "providerType": "custom",
+ "providerId": "p1",
+ "externalModel": "some-self-hosted-model",
+ "maxOutputTokens": 30_000,
+ "maxOutputTokensFromSavedCap": True,
+ }
+ monkeypatch.setattr(
+ research_runs.providers_db, "get_provider", lambda _id: {"max_output_tokens": 30_000}
+ )
+ assert _synthesis_max_tokens(inference, 900) == 30_000
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ assert _synthesis_max_tokens(inference, 900) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_clearing_the_saved_cap_leaves_a_published_ceiling_standing(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 32_768,
+ "maxOutputTokensFromSavedCap": False,
+ }
+ assert _synthesis_max_tokens(inference, 900) == 32_768
+
+
+def test_a_run_created_before_the_grounding_flag_is_unchanged(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "custom",
+ "providerId": "p1",
+ "externalModel": "some-self-hosted-model",
+ "maxOutputTokens": 30_000,
+ }
+ assert _synthesis_max_tokens(inference, 900) == 30_000
+
+
+def test_a_client_ceiling_below_the_default_still_lowers_the_budget(monkeypatch):
+ """A published limit is the model's own, not a preference: asking past it is refused.
+
+ It has to be the PUBLISHED one; maxOutputTokens alone cannot say which of the two it is.
+ """
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "openai",
+ "providerId": "p1",
+ "maxOutputTokens": 8_192,
+ "maxOutputTokensPublished": 8_192,
+ }
+ assert _synthesis_max_tokens(inference) == 8_192
+
+
+def test_an_unreadable_cap_does_not_let_a_stale_client_ceiling_through(monkeypatch):
+ def explode(_id):
+ raise sqlite3.OperationalError("database is locked")
+
+ monkeypatch.setattr(research_runs, "_CAP_LOOKUP_RETRY_SECONDS", 0)
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", explode)
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 65_536}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_an_unreadable_cap_still_honours_a_lower_client_ceiling(monkeypatch):
+ def explode(_id):
+ raise sqlite3.OperationalError("database is locked")
+
+ monkeypatch.setattr(research_runs, "_CAP_LOOKUP_RETRY_SECONDS", 0)
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", explode)
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 4_096}
+ assert _synthesis_max_tokens(inference) == 4_096
+
+
+def test_a_transient_cap_lookup_failure_is_retried(monkeypatch):
+ calls = {"n": 0}
+
+ def flaky(_id):
+ calls["n"] += 1
+ if calls["n"] < 2:
+ raise sqlite3.OperationalError("database is locked")
+ return {"max_output_tokens": 65_536}
+
+ monkeypatch.setattr(research_runs, "_CAP_LOOKUP_RETRY_SECONDS", 0)
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", flaky)
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 65_536}
+ assert _synthesis_max_tokens(inference) == 65_536
+ assert calls["n"] == 2
+
+
+def test_an_external_truncation_is_not_blamed_on_the_local_context(monkeypatch):
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda _inf = None: 8_192)
+ usage = {"prompt_tokens": 5_000, "completion_tokens": 4_000, "total_tokens": 9_000}
+ notice = _synthesis_length_limit_error(
+ usage,
+ requested_max_tokens = 32_768,
+ inference = {"providerType": "gemini", "providerId": "p1"},
+ )
+ assert "Context Length" not in notice
+ assert "Local model" not in notice
+
+
+def test_a_local_truncation_still_names_the_context_window(monkeypatch):
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda _inf = None: 8_192)
+ usage = {"prompt_tokens": 5_000, "completion_tokens": 4_000, "total_tokens": 9_000}
+ notice = _synthesis_length_limit_error(usage, requested_max_tokens = 16_384)
+ assert "Context Length" in notice
+
+
+def test_a_local_run_keeps_the_default_report_budget():
+ assert _synthesis_max_tokens({"model": "local-model"}) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_client_resolved_ceiling_is_used_verbatim(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 65_536,
+ }
+ assert _synthesis_max_tokens(inference) == 65_536
+
+
+def test_a_ceiling_below_the_default_is_respected(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "openai",
+ "providerId": "p1",
+ "maxOutputTokens": 8_192,
+ "maxOutputTokensPublished": 8_192,
+ }
+ assert _synthesis_max_tokens(inference) == 8_192
+
+
+def test_a_legacy_ceiling_below_the_default_keeps_the_old_budget(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {"providerType": "openai", "providerId": "p1", "maxOutputTokens": 8_192}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_the_provider_floor_table_matches_the_client_one_it_mirrors():
+ """A hand copy of the client's table, in another language, with nothing tying them together.
+
+ Drift is silent: the report would ask for a budget the provider truncates a thinking answer
+ below, which is what the floor exists to prevent.
+ """
+ import re
+
+ source = (
+ Path(__file__).resolve().parents[2]
+ / "frontend"
+ / "src"
+ / "features"
+ / "chat"
+ / "provider-capabilities.ts"
+ ).read_text(encoding = "utf-8")
+ table = re.search(
+ r"const EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER: Record<string, number> = \{(.*?)\};",
+ source,
+ re.S,
+ )
+ assert table, "the client table was renamed; the copy in research_runs.py needs the same"
+ assert research_runs._EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER == {
+ name: int(value.replace("_", ""))
+ for name, value in re.findall(r"(\w+)\s*:\s*([\d_]+)", table.group(1))
+ }
+ default = re.search(
+ r"export function getExternalMinOutputTokens\(.*?\)\s*:\s*number\s*\{.*?"
+ r"if \(!providerType\) return (\d+);",
+ source,
+ re.S,
+ )
+ assert default and research_runs._EXTERNAL_MIN_OUTPUT_TOKENS == int(default.group(1))
+
+
+def test_a_local_run_ignores_a_stray_ceiling():
+ assert _synthesis_max_tokens({"maxOutputTokens": 65_536}) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_budget_the_run_cannot_stream_in_time_is_bounded_by_its_wall_clock(monkeypatch):
+ """A wall-clock stop loses the report; running out of budget only truncates it.
+
+ _stream_completion re-raises without returning the text it already streamed.
+ """
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {"providerType": "deepseek", "providerId": "p1", "maxOutputTokens": 384_000}
+ assert _synthesis_max_tokens(inference, 900) == 900 * research_runs._SYNTHESIS_TOKENS_PER_SECOND
+ # Never below what the run would have got anyway.
+ assert _synthesis_max_tokens(inference, 60) == research_runs._SYNTHESIS_MAX_TOKENS
+ assert _synthesis_max_tokens({**inference, "maxOutputTokens": 32_768}, 120) == 16_384
+
+
+def test_a_ceiling_bounds_a_budget_even_without_a_wall_clock(monkeypatch):
+ """0 is unlimited in the budgets schema, and a documented cap can still be wrong."""
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {"providerType": "deepseek", "providerId": "p1", "maxOutputTokens": 384_000}
+ for unlimited in (0, None):
+ assert _synthesis_max_tokens(inference, unlimited) == (
+ research_runs._SYNTHESIS_MAX_TOKENS_CEILING
+ )
+
+
+def test_an_absurd_saved_ceiling_cannot_reach_the_provider(monkeypatch):
+ """The route accepts up to MAX_JSON_SAFE_INTEGER, and nothing downstream bounds it."""
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id: {"max_output_tokens": 9_007_199_254_740_991},
+ )
+ inference = {
+ "providerType": "openai",
+ "providerId": "p1",
+ "maxOutputTokens": 9_007_199_254_740_991,
+ }
+ assert _synthesis_max_tokens(inference, 900) <= research_runs._SYNTHESIS_MAX_TOKENS_CEILING
+
+
+def test_the_report_budget_never_falls_below_what_a_run_used_to_get(monkeypatch):
+ for saved in (None, 64, 8_000, 16_384, 32_768, 256_000):
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id, cap = saved: {"max_output_tokens": cap} if cap else None,
+ )
+ for client in (None, 32_768, 65_536, 384_000):
+ inference = {"providerType": "gemini", "providerId": "p1"}
+ if client:
+ inference["maxOutputTokens"] = client
+ budget = _synthesis_max_tokens(inference, 900)
+ assert budget >= research_runs._SYNTHESIS_MAX_TOKENS, (saved, client, budget)
+ assert budget <= research_runs._SYNTHESIS_MAX_TOKENS_CEILING, (saved, client, budget)
+
+
+def test_a_cap_lowered_mid_run_bounds_the_request_that_actually_goes_out(monkeypatch):
+ """Recovery and every retry rebuild the request later, so the cap is re-read at build."""
+ caps = iter([65_536, 32_768])
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id: {"max_output_tokens": next(caps, 32_768)},
+ )
+ inference = {"providerType": "gemini", "providerId": "p1", "maxOutputTokens": 65_536}
+ assert _synthesis_max_tokens(inference, 0) == 65_536
+ # The second call is the one the retry loop makes.
+ assert _synthesis_max_tokens(inference, 0) == 32_768
+
+
+def test_the_flush_triggers_scale_from_the_same_written_length():
+ """Both arms must start scaling together, or the character one never binds.
+
+ A time arm whose knee sits at the END of the unlocked range leaves the row rewritten four
+ times a second through the shared writer for an entire 65_536-token report.
+ """
+ knee = int(
+ research_runs._PROGRESS_FLUSH_SECONDS * research_runs._PROGRESS_FLUSH_CHARS_PER_SECOND
+ )
+ assert knee == research_runs._PROGRESS_FLUSH_CHARS * 64
+ # A 65_536-token report is roughly 262_144 chars; the arm must scale well before it.
+ assert knee < 262_144 // 2
+ assert max(research_runs._PROGRESS_FLUSH_CHARS, 1_000 // 64) == 512
+ assert (
+ max(
+ research_runs._PROGRESS_FLUSH_SECONDS,
+ 1_000 / research_runs._PROGRESS_FLUSH_CHARS_PER_SECOND,
+ )
+ == 0.25
+ )
+
+
+def test_an_explicit_zero_budget_is_never_put_on_the_wire(monkeypatch):
+ """main's `max_tokens or ...` made 0 impossible; the route rejects a request for one."""
+ monkeypatch.setattr(research_runs, "_loaded_context_length", lambda *a, **k: None)
+ assert _resolve_max_tokens(0, {}, [{"role": "user", "content": "x"}]) == 1
+ assert _resolve_max_tokens(-5, {}, [{"role": "user", "content": "x"}]) == 1
+
+
+def test_a_saved_connection_cap_does_not_shorten_a_legacy_run(monkeypatch):
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id: {"max_output_tokens": 8_192},
+ )
+ inference = {"providerType": "ollama", "providerId": "p1", "externalModel": "glm-5.3-flash"}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_saved_cap_above_the_default_does_not_raise_a_legacy_run(monkeypatch):
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id: {"max_output_tokens": 32_768},
+ )
+ inference = {"providerType": "ollama", "providerId": "p1", "externalModel": "glm-5.3-flash"}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_a_client_ceiling_is_what_actually_raises_the_report_budget(monkeypatch):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: None)
+ inference = {
+ "providerType": "ollama",
+ "providerId": "p1",
+ "externalModel": "glm-5.3-flash",
+ "maxOutputTokens": 32_768,
+ }
+ assert _synthesis_max_tokens(inference) == 32_768
+
+
+def test_a_legacy_run_keeps_the_default_rather_than_guessing_upwards(monkeypatch):
+ """The saved cap is connection-wide, so for this run's model it is a guess: claude-opus-4-1
+ stops at 32_000 while its connection may be saved at 32_768."""
+ monkeypatch.setattr(
+ research_runs.providers_db,
+ "get_provider",
+ lambda _id: {"max_output_tokens": 256_000},
+ )
+ inference = {"providerType": "gemini", "providerId": "p1", "externalModel": "gemini-3.6-flash"}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+ "provider",
+ [None, {}, {"max_output_tokens": None}, {"max_output_tokens": 0}],
+ ids = ["missing", "unset", "null", "zero"],
+)
+def test_a_connection_without_a_saved_cap_keeps_the_default(monkeypatch, provider):
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", lambda _id: provider)
+ inference = {"providerType": "ollama", "providerId": "p1"}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
+def test_an_unreadable_provider_row_does_not_fail_the_run(monkeypatch):
+ def explode(_id):
+ raise sqlite3.OperationalError("database is locked")
+
+ monkeypatch.setattr(research_runs.providers_db, "get_provider", explode)
+ inference = {"providerType": "ollama", "providerId": "p1"}
+ assert _synthesis_max_tokens(inference) == research_runs._SYNTHESIS_MAX_TOKENS
+
+
def test_completion_hit_context_wall_matches_live_probe():
usage = {
"prompt_tokens": 11_032,
@@ -488,6 +966,43 @@ def test_budgets_reject_a_boolean_instead_of_reading_it_as_unlimited():
}
+def test_sanitize_config_rejects_a_non_integer_report_ceiling():
+ for bad in (True, 64.9, float("inf"), float("nan"), "32768"):
+ with pytest.raises(HTTPException):
+ _sanitize_config(
+ _make_payload(inferenceRequest = {"model": "m", "maxOutputTokens": bad}),
+ {"modelId": "m"},
+ )
+
+
+def test_sanitize_config_keeps_a_strict_integer_report_ceiling():
+ config = _sanitize_config(
+ _make_payload(inferenceRequest = {"model": "m", "maxOutputTokens": 32_768}),
+ {"modelId": "m"},
+ )
+ assert config["inferenceRequest"]["maxOutputTokens"] == 32_768
+
+
+def test_sanitize_config_keeps_the_grounding_flag_and_refuses_a_non_boolean():
+ config = _sanitize_config(
+ _make_payload(
+ inferenceRequest = {
+ "model": "m",
+ "maxOutputTokens": 32_768,
+ "maxOutputTokensFromSavedCap": True,
+ }
+ ),
+ {"modelId": "m"},
+ )
+ assert config["inferenceRequest"]["maxOutputTokensFromSavedCap"] is True
+ for bad in (1, 0, "true", None, []):
+ with pytest.raises(HTTPException):
+ _sanitize_config(
+ _make_payload(inferenceRequest = {"model": "m", "maxOutputTokensFromSavedCap": bad}),
+ {"modelId": "m"},
+ )
+
+
def test_sanitize_config_rejects_nested_inference_credential():
payload = _make_payload(inferenceRequest = {"model": {"api_key": "sk-should-not-persist"}})
with pytest.raises(Exception):
diff --git a/studio/backend/tests/test_research_synthesis_recovery.py b/studio/backend/tests/test_research_synthesis_recovery.py
index 648d28b5512..2e06215cbc5 100644
--- a/studio/backend/tests/test_research_synthesis_recovery.py
+++ b/studio/backend/tests/test_research_synthesis_recovery.py
@@ -43,7 +43,7 @@ def research_home(tmp_path, monkeypatch):
return tmp_path
-def _claimed_run(supervisor) -> dict:
+def _claimed_run(supervisor, external: bool = False) -> dict:
research_db.create_run(
run_id = "run-1",
owner_subject = "alice",
@@ -52,14 +52,24 @@ def _claimed_run(supervisor) -> dict:
assistant_message_id = None,
config = {
"model": "local-model",
- "inferenceRequest": {"model": "local-model"},
+ "inferenceRequest": (
+ {
+ "model": "local-model",
+ "providerType": "gemini",
+ "providerId": "p1",
+ "externalModel": "gemini-3.6-flash",
+ "maxOutputTokens": 32_768,
+ }
+ if external
+ else {"model": "local-model"}
+ ),
"ragScope": None,
"instructions": "",
"question": "what happened?",
"budgets": {
"maxSteps": 1,
"maxSources": 5,
- "modelTimeoutSeconds": 30,
+ "modelTimeoutSeconds": 900,
"toolTimeoutSeconds": 10,
},
},
@@ -283,3 +293,111 @@ def test_a_recovery_padded_with_invented_citations_does_not_win_on_length(
assert len(SHORTER_DRAFT + "\n\n" + invented) > len(FIRST_DRAFT)
assert finished["status"] == "completed"
assert FIRST_DRAFT in finished["report"]
+
+
+def test_a_refused_report_budget_falls_back_rather_than_losing_the_run(research_home, monkeypatch):
+ """None of the ways a connection can refuse are knowable when the budget is resolved, so
+ the last attempt is made at the budget every run had before the ceiling was read."""
+ from core import research_runs as worker
+
+ supervisor = worker.ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 1)))
+ monkeypatch.setattr(
+ worker.providers_db, "get_provider", lambda _id: {"max_output_tokens": 32_768}
+ )
+ claimed = _claimed_run(supervisor, external = True)
+ asked: list[int | None] = []
+
+ async def refuse_the_raised_budget(run, messages, **kwargs):
+ if kwargs.get("phase") != "synthesis":
+ return "not json", "", "stop", None
+ budget = kwargs.get("max_tokens")
+ asked.append(budget)
+ if budget and budget > worker._SYNTHESIS_MAX_TOKENS:
+ raise ValueError("max_tokens is too large for this model")
+ return FIRST_DRAFT, "", "stop", None
+
+ monkeypatch.setattr(supervisor, "_stream_completion", refuse_the_raised_budget)
+ asyncio.run(supervisor._research(claimed))
+
+ assert asked == [32_768, worker._SYNTHESIS_MAX_TOKENS]
+ finished = research_db.get_run("run-1")
+ assert finished["status"] == "completed"
+ assert FIRST_DRAFT in finished["report"]
+
+
+def test_a_cancelled_run_is_not_retried_at_the_old_budget(research_home, monkeypatch):
+ """The fallback covers a refused budget, not a run the user stopped."""
+ from core import research_runs as worker
+
+ supervisor = worker.ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 1)))
+ monkeypatch.setattr(
+ worker.providers_db, "get_provider", lambda _id: {"max_output_tokens": 32_768}
+ )
+ claimed = _claimed_run(supervisor, external = True)
+ calls = {"n": 0}
+
+ async def cancel_during_synthesis(run, messages, **kwargs):
+ if kwargs.get("phase") != "synthesis":
+ return "not json", "", "stop", None
+ calls["n"] += 1
+ raise worker.RunCancelled()
+
+ monkeypatch.setattr(supervisor, "_stream_completion", cancel_during_synthesis)
+ with pytest.raises(worker.RunCancelled):
+ asyncio.run(supervisor._research(claimed))
+
+ assert calls["n"] == 1
+
+
+def test_a_failed_recovery_keeps_the_draft_it_was_called_to_rescue(research_home, monkeypatch):
+ """Its prompt carries instructions the first did not, so an endpoint counting prompt plus
+ output against one window can refuse it at a budget the first request fit inside."""
+ from core import research_runs as worker
+
+ supervisor = worker.ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 1)))
+ monkeypatch.setattr(
+ worker.providers_db, "get_provider", lambda _id: {"max_output_tokens": 32_768}
+ )
+ claimed = _claimed_run(supervisor, external = True)
+ phases: list[str] = []
+
+ async def refuse_only_the_recovery(run, messages, **kwargs):
+ phase = kwargs.get("phase")
+ phases.append(phase)
+ if phase == "synthesis":
+ return FIRST_DRAFT, "", "length", {"completion_tokens": 32_768}
+ if phase == "synthesis_recovery":
+ raise ValueError("max_tokens plus prompt exceeds the model's context window")
+ return "not json", "", "stop", None
+
+ monkeypatch.setattr(supervisor, "_stream_completion", refuse_only_the_recovery)
+ asyncio.run(supervisor._research(claimed))
+
+ assert "synthesis_recovery" in phases
+ finished = research_db.get_run("run-1")
+ assert finished["status"] == "completed"
+ assert FIRST_DRAFT in finished["report"]
+ assert "Incomplete report." in finished["report"]
+
+
+def test_a_cancel_during_recovery_still_stops_the_run(research_home, monkeypatch):
+ """The rescue covers a refused request, not a run the user stopped."""
+ from core import research_runs as worker
+
+ supervisor = worker.ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 1)))
+ monkeypatch.setattr(
+ worker.providers_db, "get_provider", lambda _id: {"max_output_tokens": 32_768}
+ )
+ claimed = _claimed_run(supervisor, external = True)
+
+ async def cancel_during_recovery(run, messages, **kwargs):
+ phase = kwargs.get("phase")
+ if phase == "synthesis":
+ return FIRST_DRAFT, "", "length", {"completion_tokens": 32_768}
+ if phase == "synthesis_recovery":
+ raise worker.RunCancelled()
+ return "not json", "", "stop", None
+
+ monkeypatch.setattr(supervisor, "_stream_completion", cancel_during_recovery)
+ with pytest.raises(worker.RunCancelled):
+ asyncio.run(supervisor._research(claimed))
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 026e1f3e0a2..7436465a45b 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -140,7 +140,10 @@ import {
import { syncModelCapabilities } from "../hooks/use-chat-model-runtime";
import {
clampReasoningEffortToLevels,
+ externalMaxOutputTokensNeedsConnectionCap,
getExternalMaxOutputTokens,
+ getPublishedExternalMaxOutputTokens,
+ getGroundedExternalMaxOutputTokens,
getExternalMinOutputTokens,
getExternalReasoningCapabilities,
getProviderCapabilities,
@@ -4158,6 +4161,19 @@ export function createOpenAIStreamAdapter(
providerId: researchExternalProvider.id,
providerType: researchExternalProvider.providerType,
modelId: researchExternalSelection.modelId,
+ maxOutputTokens: getGroundedExternalMaxOutputTokens(
+ researchExternalProvider.providerType,
+ researchExternalSelection.modelId,
+ researchExternalProvider.maxOutputTokens,
+ ),
+ maxOutputTokensFromSavedCap: externalMaxOutputTokensNeedsConnectionCap(
+ researchExternalProvider.providerType,
+ researchExternalSelection.modelId,
+ ),
+ maxOutputTokensPublished: getPublishedExternalMaxOutputTokens(
+ researchExternalProvider.providerType,
+ researchExternalSelection.modelId,
+ ),
}
: undefined,
temperature: params.temperature,
diff --git a/studio/frontend/src/features/chat/provider-capabilities.ts b/studio/frontend/src/features/chat/provider-capabilities.ts
index 84ceaa9ce8d..f8fb4e8d4bc 100644
--- a/studio/frontend/src/features/chat/provider-capabilities.ts
+++ b/studio/frontend/src/features/chat/provider-capabilities.ts
@@ -165,8 +165,63 @@ export function getExternalMaxOutputTokens(
return Math.max(resolved, getExternalMinOutputTokens(providerType));
}
-/** The published per-model cap, or null when nothing documents this id. Generic Custom
- * connections always read undocumented. OpenRouter `provider/model` prefixes are stripped. */
+/**
+ * The ceiling only when a published cap or the user's own override grounds it, else null.
+ * `getExternalMaxOutputTokens` guesses for an undocumented model, which is fine for a slider
+ * but not as a budget: a 32k-context self-hosted server holds the prompt in the same window.
+ */
+export function getGroundedExternalMaxOutputTokens(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+ connectionMaxOutputTokens?: number | null,
+): number | null {
+ const override = normalizeProviderMaxOutputTokens(connectionMaxOutputTokens);
+ if (override == null && _publishedMaxOutputTokens(providerType, modelId) == null) return null;
+ return getExternalMaxOutputTokens(providerType, modelId, connectionMaxOutputTokens);
+}
+
+/**
+ * True when the connection's override is the ONLY thing that can ground this model's ceiling.
+ * A durable run carries the ceiling it was created with, and the backend can see the cap is
+ * gone but not whether anything else was holding the number up.
+ */
+export function externalMaxOutputTokensNeedsConnectionCap(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): boolean {
+ return _publishedMaxOutputTokens(providerType, modelId) == null;
+}
+
+/**
+ * The model's own published output limit, before any connection override is folded in. The
+ * folded number cannot tell a model that stops at 8192 from a 65536 model capped at 8192,
+ * and only the first may lower the report budget.
+ */
+export function getPublishedExternalMaxOutputTokens(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): number | null {
+ return _publishedMaxOutputTokens(providerType, modelId);
+}
+
+/**
+ * `_documentedMaxOutputTokens`, minus entries that do not survive being sent unattended: an
+ * OpenRouter id resolves through the DIRECT provider's table, so `deepseek/deepseek-r1` reads
+ * as 384000 while the router serves it far below that.
+ */
+function _publishedMaxOutputTokens(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): number | null {
+ if (providerType === "openrouter") return null;
+ return _documentedMaxOutputTokens(providerType, modelId);
+}
+
+/**
+ * The published per-model cap, or null when nothing documents this id. No table entry
+ * targets a generic Custom connection, so those always read as undocumented. OpenRouter
+ * `provider/model` ids have the prefix stripped before matching.
+ */
function _documentedMaxOutputTokens(
providerType: string | null | undefined,
modelId: string | null | undefined,
diff --git a/studio/frontend/src/features/chat/research-inference-request.ts b/studio/frontend/src/features/chat/research-inference-request.ts
index 5fbc5eea10e..d41446078bf 100644
--- a/studio/frontend/src/features/chat/research-inference-request.ts
+++ b/studio/frontend/src/features/chat/research-inference-request.ts
@@ -19,13 +19,26 @@ export interface ResearchInferenceRequest {
temperature?: number;
topP?: number;
maxTokens?: number;
+ maxOutputTokens?: number;
+ maxOutputTokensFromSavedCap?: boolean;
+ maxOutputTokensPublished?: number;
enableThinking?: boolean;
reasoningEffort?: string;
}
export function buildResearchInferenceRequest(input: {
checkpoint: string;
- external?: { providerId: string; providerType: string; modelId: string };
+ external?: {
+ providerId: string;
+ providerType: string;
+ modelId: string;
+ /** The connection's resolved output ceiling, or null when nothing grounds one. */
+ maxOutputTokens: number | null;
+ /** True when the connection's saved cap is the only thing grounding that ceiling. */
+ maxOutputTokensFromSavedCap: boolean;
+ /** The model's own published limit, before the connection override is folded in. */
+ maxOutputTokensPublished: number | null;
+ };
temperature: number;
topP: number;
maxTokens: number;
@@ -46,6 +59,26 @@ export function buildResearchInferenceRequest(input: {
providerId: input.external.providerId,
providerType: input.external.providerType,
externalModel: input.external.modelId,
+ ...(input.external.maxOutputTokens != null &&
+ Number.isFinite(input.external.maxOutputTokens) &&
+ input.external.maxOutputTokens > 0
+ ? {
+ maxOutputTokens: Math.floor(input.external.maxOutputTokens),
+ // The run outlives the connection edit that grounded it.
+ maxOutputTokensFromSavedCap: input.external.maxOutputTokensFromSavedCap,
+ // The ceiling above has the override folded in, so it cannot say whether the
+ // model itself stops there, which is what the report floor turns on.
+ ...(input.external.maxOutputTokensPublished != null &&
+ Number.isFinite(input.external.maxOutputTokensPublished) &&
+ input.external.maxOutputTokensPublished > 0
+ ? {
+ maxOutputTokensPublished: Math.floor(
+ input.external.maxOutputTokensPublished,
+ ),
+ }
+ : {}),
+ }
+ : {}),
}
: {}),
};
diff --git a/studio/frontend/tests/provider-max-output-tokens-guards.test.ts b/studio/frontend/tests/provider-max-output-tokens-guards.test.ts
index 23a13236e1c..c074cde8eda 100644
--- a/studio/frontend/tests/provider-max-output-tokens-guards.test.ts
+++ b/studio/frontend/tests/provider-max-output-tokens-guards.test.ts
@@ -26,6 +26,9 @@ const {
EXTERNAL_MAX_OUTPUT_TOKENS,
getExternalMaxOutputTokens,
getExternalMinOutputTokens,
+ externalMaxOutputTokensNeedsConnectionCap,
+ getGroundedExternalMaxOutputTokens,
+ getPublishedExternalMaxOutputTokens,
resolveExternalMaxTokensClamp,
} = await import("../src/features/chat/provider-capabilities.ts");
@@ -260,3 +263,67 @@ test("every clamp site waits for a resolved provider", () => {
/if \(provider\) \{\s*const cap = getExternalMaxOutputTokens\(\s*provider\.providerType/,
);
});
+
+
+test("a grounded ceiling is only sent when something documents or overrides it", () => {
+ // The generic 32768 fallback is a guess: a 32k-context server holds the prompt too.
+ assert.equal(getExternalMaxOutputTokens("custom", "some-self-hosted-model", null), 32768);
+ assert.equal(
+ getGroundedExternalMaxOutputTokens("custom", "some-self-hosted-model", null),
+ null,
+ );
+
+ assert.equal(
+ getGroundedExternalMaxOutputTokens("custom", "some-self-hosted-model", 20000),
+ 20000,
+ );
+
+ assert.equal(
+ getGroundedExternalMaxOutputTokens("gemini", "gemini-3.6-flash", null),
+ getExternalMaxOutputTokens("gemini", "gemini-3.6-flash", null),
+ );
+});
+
+test("an openrouter model is not grounded by the direct provider's published cap", () => {
+ // The id resolves through the DIRECT provider's table; the router serves it far below.
+ assert.equal(
+ getExternalMaxOutputTokens("openrouter", "deepseek/deepseek-r1-0528", null),
+ 384000,
+ );
+ assert.equal(
+ getGroundedExternalMaxOutputTokens("openrouter", "deepseek/deepseek-r1-0528", null),
+ null,
+ );
+
+ assert.equal(
+ getGroundedExternalMaxOutputTokens("openrouter", "deepseek/deepseek-r1-0528", 32000),
+ 32000,
+ );
+});
+
+test("the grounding of a ceiling is reported alongside it", () => {
+ assert.equal(
+ externalMaxOutputTokensNeedsConnectionCap("custom", "some-self-hosted-model"),
+ true,
+ );
+ // A router id resolves through a table that does not describe the endpoint.
+ assert.equal(
+ externalMaxOutputTokensNeedsConnectionCap("openrouter", "deepseek/deepseek-r1-0528"),
+ true,
+ );
+ assert.equal(externalMaxOutputTokensNeedsConnectionCap("gemini", "gemini-3.6-flash"), false);
+});
+
+test("the published ceiling is reported without the override folded in", () => {
+ // A 65536 model capped at 8192 must stay distinguishable from one that stops at 8192.
+ assert.equal(getPublishedExternalMaxOutputTokens("gemini", "gemini-3.6-flash"), 65536);
+ assert.equal(
+ getExternalMaxOutputTokens("gemini", "gemini-3.6-flash", 8192),
+ 8192,
+ );
+ assert.equal(getPublishedExternalMaxOutputTokens("custom", "some-self-hosted-model"), null);
+ assert.equal(
+ getPublishedExternalMaxOutputTokens("openrouter", "deepseek/deepseek-r1-0528"),
+ null,
+ );
+});
diff --git a/studio/frontend/tests/research-inference-request.test.ts b/studio/frontend/tests/research-inference-request.test.ts
index 2309e9a40dd..6b8aee8bb8d 100644
--- a/studio/frontend/tests/research-inference-request.test.ts
+++ b/studio/frontend/tests/research-inference-request.test.ts
@@ -17,6 +17,9 @@ test("Codex research keeps provider routing and clamps generation settings", ()
providerId: "provider",
providerType: "openai_codex",
modelId: "gpt-5.6-sol",
+ maxOutputTokens: 128000,
+ maxOutputTokensFromSavedCap: false,
+ maxOutputTokensPublished: null,
},
temperature: 0.2,
topP: 0.9,
@@ -32,6 +35,8 @@ test("Codex research keeps provider routing and clamps generation settings", ()
providerId: "provider",
providerType: "openai_codex",
externalModel: "gpt-5.6-sol",
+ maxOutputTokens: 128000,
+ maxOutputTokensFromSavedCap: false,
temperature: 0.2,
topP: 0.9,
maxTokens: 8192,
@@ -56,3 +61,130 @@ test("invalid optional settings do not leak into a local research request", () =
{ model: "local/model.gguf", enableThinking: false },
);
});
+
+test("the report ceiling the connection resolved reaches the run config", () => {
+ const request = buildResearchInferenceRequest({
+ checkpoint: "external::provider::gemini-3.6-flash",
+ external: {
+ providerId: "provider",
+ providerType: "gemini",
+ modelId: "gemini-3.6-flash",
+ maxOutputTokens: 65536,
+ maxOutputTokensFromSavedCap: false,
+ maxOutputTokensPublished: null,
+ },
+ temperature: 0.2,
+ topP: 0.9,
+ maxTokens: 4096,
+ reasoningRequested: false,
+ reasoningStyle: "none",
+ reasoningEffort: "low",
+ reasoningEffortLevels: ["low", "medium", "high"],
+ clampReasoningEffort: clamp,
+ });
+
+ assert.equal(request.maxOutputTokens, 65536);
+ assert.equal(request.maxTokens, 4096);
+});
+
+test("an undocumented model with no connection override sends no ceiling", () => {
+ const request = buildResearchInferenceRequest({
+ checkpoint: "local-model",
+ external: {
+ providerId: "provider",
+ providerType: "custom",
+ modelId: "some-self-hosted-model",
+ // What getGroundedExternalMaxOutputTokens returns when nothing documents the model.
+ maxOutputTokens: null,
+ maxOutputTokensFromSavedCap: false,
+ maxOutputTokensPublished: null,
+ },
+ temperature: 0.2,
+ topP: 0.9,
+ maxTokens: 4096,
+ reasoningRequested: false,
+ reasoningStyle: "none",
+ reasoningEffort: "low",
+ reasoningEffortLevels: ["low", "medium", "high"],
+ clampReasoningEffort: clamp,
+ });
+ assert.equal("maxOutputTokens" in request, false);
+});
+
+test("an explicit connection override is still sent", () => {
+ const request = buildResearchInferenceRequest({
+ checkpoint: "local-model",
+ external: {
+ providerId: "provider",
+ providerType: "custom",
+ modelId: "some-self-hosted-model",
+ maxOutputTokens: 20000,
+ maxOutputTokensFromSavedCap: false,
+ maxOutputTokensPublished: null,
+ },
+ temperature: 0.2,
+ topP: 0.9,
+ maxTokens: 4096,
+ reasoningRequested: false,
+ reasoningStyle: "none",
+ reasoningEffort: "low",
+ reasoningEffortLevels: ["low", "medium", "high"],
+ clampReasoningEffort: clamp,
+ });
+ assert.equal(request.maxOutputTokens, 20000);
+});
+
+test("the request says whether the saved cap is what grounded its ceiling", () => {
+ const build = (maxOutputTokensFromSavedCap: boolean, maxOutputTokens: number | null) =>
+ buildResearchInferenceRequest({
+ checkpoint: "external::p1::some-self-hosted-model",
+ external: {
+ providerId: "p1",
+ providerType: "custom",
+ modelId: "some-self-hosted-model",
+ maxOutputTokens,
+ maxOutputTokensFromSavedCap,
+ maxOutputTokensPublished: null,
+ },
+ temperature: 0.2,
+ topP: 0.9,
+ maxTokens: 4096,
+ reasoningRequested: false,
+ reasoningStyle: "none",
+ reasoningEffort: "medium",
+ reasoningEffortLevels: ["low", "medium", "high"],
+ clampReasoningEffort: clamp,
+ });
+
+ assert.equal(build(true, 30000).maxOutputTokensFromSavedCap, true);
+ assert.equal(build(false, 30000).maxOutputTokensFromSavedCap, false);
+ // No ceiling to qualify, so the flag has nothing to say and is left off entirely.
+ assert.equal("maxOutputTokensFromSavedCap" in build(true, null), false);
+});
+
+test("the published ceiling rides along, unfolded, when the model has one", () => {
+ const request = buildResearchInferenceRequest({
+ checkpoint: "external::p1::gemini-3.6-flash",
+ external: {
+ providerId: "p1",
+ providerType: "gemini",
+ modelId: "gemini-3.6-flash",
+ // What the connection actually spends: the override folded into the published cap.
+ maxOutputTokens: 8192,
+ maxOutputTokensFromSavedCap: false,
+ maxOutputTokensPublished: 65536,
+ },
+ temperature: 0.2,
+ topP: 0.9,
+ maxTokens: 4096,
+ reasoningRequested: false,
+ reasoningStyle: "none",
+ reasoningEffort: "low",
+ reasoningEffortLevels: ["low", "medium", "high"],
+ clampReasoningEffort: clamp,
+ });
+
+ // The backend needs the pair to tell a capped connection from a 8192-token model.
+ assert.equal(request.maxOutputTokens, 8192);
+ assert.equal(request.maxOutputTokensPublished, 65536);
+});