Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(model-hub): fast mode per Session from the Web model picker (#3088)

Call Whitebad9d77ae088
diff --git a/config/v2_config.py b/config/v2_config.py
index aa0711f9f..d7a18a9a0 100644
--- a/config/v2_config.py
+++ b/config/v2_config.py
@@ -2732,6 +2732,7 @@ class ModelHubBackendModelConfig:
"locked",
"routeable",
"effort_menu",
+ "fast_mode",
}
if set(payload) - allowed:
raise ValueError("Config 'model_hub.agents.models' contains unknown fields")
diff --git a/core/agent_session_context.py b/core/agent_session_context.py
index 9fa559ff1..945bc4bc4 100644
--- a/core/agent_session_context.py
+++ b/core/agent_session_context.py
@@ -15,3 +15,17 @@ def resolve_context_agent_session_target(context: Any) -> Optional[dict[str, Any
if not isinstance(run_target, dict) or not run_target.get("agent_session_id"):
return None
return {**run_target, "id": run_target["agent_session_id"]}
+
+
+def session_speed_for_context(context: Any) -> Optional[str]:
+ """The processing tier the Session this context runs in asks for: ``"fast"``, or None for standard.
+
+ Read from the Session row dispatch copied onto the context (its ``metadata``);
+ a context without a Session row, such as an Agent run's, runs at the standard tier.
+ """
+
+ from storage.agent_session_rows import session_speed
+
+ payload = getattr(context, "platform_specific", None) or {}
+ target = payload.get("agent_session_target")
+ return session_speed(target.get("metadata")) if isinstance(target, dict) else None
diff --git a/core/handlers/model_hub/fast_mode.py b/core/handlers/model_hub/fast_mode.py
new file mode 100644
index 000000000..11a9fdb78
--- /dev/null
+++ b/core/handlers/model_hub/fast_mode.py
@@ -0,0 +1,153 @@
+"""Fast mode: a Session's opt-in to a vendor's faster, pricier processing tier.
+
+docs/plans/fast-mode.md. A Session that turns fast mode on asks every Model
+Hub attempt of its turns to run at the vendor's fast tier where that attempt's
+exact (Source, model) is known to offer one, and at the standard tier anywhere
+else. The request field that selects the tier is read from the models.dev entry
+of the model's first-party vendor (``experimental.modes.fast``), which also
+covers new models without a release:
+
+- OpenAI (GPT, o-series): ``service_tier: "priority"`` on Responses and Chat
+ Completions requests.
+- Anthropic (Claude Opus): ``speed: "fast"`` on Messages requests. The engine
+ adds the beta header a model needs.
+
+Only that vendor's own upstream honours the field: an API key on the vendor's
+official endpoint, or the vendor's subscription held by the Model Hub. A request
+is never translated across protocols to reach a fast tier. Reading the catalog
+never fetches: an absent or unreadable copy offers fast mode nowhere.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Final, Mapping, Optional
+
+from vibe.backend_model_catalog import catalog_model_id
+
+logger = logging.getLogger(__name__)
+
+FAST_SPEED: Final = "fast"
+
+# The vendors whose fast tier Avibe drives, the request protocols each one's
+# field belongs to, and the one body field each may set. A catalog entry that
+# asks for anything else is not applied.
+_VENDOR_PROTOCOLS: Final[Mapping[str, frozenset[str]]] = {
+ "openai": frozenset({"openai_responses", "openai_chat"}),
+ "anthropic": frozenset({"anthropic"}),
+}
+_VENDOR_FIELDS: Final[Mapping[str, str]] = {"openai": "service_tier", "anthropic": "speed"}
+
+
+def normalized_speed(value: Any) -> Optional[str]:
+ """The stored speed a value names: ``"fast"``, or None for the standard tier."""
+
+ return FAST_SPEED if value == FAST_SPEED else None
+
+
+@dataclass(frozen=True)
+class FastModeCatalog:
+ """Each vendor's fast-tier request field by model, and which vendor makes each model family."""
+
+ bodies: Mapping[str, Mapping[str, Mapping[str, str]]] = field(default_factory=dict)
+ families: tuple[tuple[str, str], ...] = ()
+
+ @classmethod
+ def from_models_dev(cls, catalog: Mapping[str, Any], vendor_map: Mapping[str, Any]) -> "FastModeCatalog":
+ families = tuple(
+ (item["prefix"], item["vendor_id"])
+ for item in (vendor_map.get("families") if isinstance(vendor_map.get("families"), list) else ())
+ if isinstance(item, Mapping)
+ and isinstance(item.get("prefix"), str)
+ and item.get("vendor_id") in _VENDOR_FIELDS
+ )
+ bodies: dict[str, dict[str, Mapping[str, str]]] = {}
+ for vendor, field_name in _VENDOR_FIELDS.items():
+ provider = catalog.get(vendor)
+ models = provider.get("models") if isinstance(provider, Mapping) else None
+ if not isinstance(models, Mapping):
+ continue
+ for key, entry in models.items():
+ body = _fast_body(entry, field_name)
+ if body is None:
+ continue
+ names = {str(key)}
+ if isinstance(entry, Mapping) and isinstance(entry.get("id"), str):
+ names.add(entry["id"])
+ for name in names:
+ bodies.setdefault(vendor, {})[name] = body
+ return cls(bodies=bodies, families=families)
+
+ def first_party(self, model_id: str) -> Optional[str]:
+ matches = [(prefix, vendor) for prefix, vendor in self.families if model_id.startswith(prefix)]
+ return max(matches, key=lambda item: len(item[0]))[1] if matches else None
+
+ def body_for(self, source: Any, model_id: str, request_protocol: Optional[str]) -> Optional[Mapping[str, str]]:
+ """The body fields that put this exact attempt on its vendor's fast tier, or None where none applies."""
+
+ if not model_id or getattr(source, "supply_channel", None) != "hub":
+ return None
+ vendor = getattr(source, "vendor", None)
+ protocol = getattr(source, "protocol", None)
+ if (
+ vendor not in _VENDOR_PROTOCOLS
+ or protocol not in _VENDOR_PROTOCOLS[vendor]
+ or request_protocol != protocol
+ ):
+ return None
+ if getattr(source, "kind", None) == "api_key":
+ base_url = getattr(source, "base_url", None)
+ if base_url is not None:
+ from vibe.model_hub_runtime.api_key_vendors import is_official_api_key_endpoint
+
+ if not is_official_api_key_endpoint(vendor, base_url):
+ return None
+ elif getattr(source, "kind", None) != "subscription":
+ return None
+ models = self.bodies.get(vendor) or {}
+ for candidate in dict.fromkeys((model_id, catalog_model_id(model_id))):
+ if self.first_party(candidate) == vendor and candidate in models:
+ return models[candidate]
+ return None
+
+
+def _fast_body(entry: Any, field_name: str) -> Optional[Mapping[str, str]]:
+ modes = entry.get("experimental") if isinstance(entry, Mapping) else None
+ modes = modes.get("modes") if isinstance(modes, Mapping) else None
+ fast = modes.get(FAST_SPEED) if isinstance(modes, Mapping) else None
+ provider = fast.get("provider") if isinstance(fast, Mapping) else None
+ body = provider.get("body") if isinstance(provider, Mapping) else None
+ if not isinstance(body, Mapping) or set(body) != {field_name}:
+ return None
+ value = body[field_name]
+ return {field_name: value} if isinstance(value, str) and value.strip() else None
+
+
+_LOCK = threading.Lock()
+_CACHED: tuple[Optional[tuple[str, int, int]], FastModeCatalog] = (None, FastModeCatalog())
+
+
+def load_fast_mode_catalog() -> FastModeCatalog:
+ """The fast-mode index of the cached models.dev copy, rebuilt only when that copy changes.
+
+ Reads files: call it off the controller loop. Never fetches.
+ """
+
+ global _CACHED
+ from vibe import models_dev_catalog
+
+ stamp = models_dev_catalog.cached_models_dev_stamp()
+ with _LOCK:
+ if stamp is not None and _CACHED[0] == stamp:
+ return _CACHED[1]
+ try:
+ catalog = models_dev_catalog.cached_models_dev_catalog() if stamp is not None else {}
+ vendor_map = models_dev_catalog.load_model_vendor_map()
+ built = FastModeCatalog.from_models_dev(catalog, vendor_map)
+ except Exception as exc: # noqa: BLE001 - optional metadata never fails a request
+ logger.info("Model Hub has no fast-mode catalog: %s", type(exc).__name__)
+ built = FastModeCatalog()
+ _CACHED = (stamp, built)
+ return built
diff --git a/core/handlers/model_hub/opaque_provenance.py b/core/handlers/model_hub/opaque_provenance.py
index 8e77d28d6..0598f3f89 100644
--- a/core/handlers/model_hub/opaque_provenance.py
+++ b/core/handlers/model_hub/opaque_provenance.py
@@ -543,14 +543,7 @@ def filter_opaque_history(
if isinstance(result.get("contents"), list):
result["contents"] = _filter_google_contents(result["contents"], registry, identity)
if isinstance(payload, ModelHubRequest):
- return ModelHubRequest(
- result,
- protocol=payload.protocol,
- headers=payload.headers,
- primary_origin=payload.primary_origin,
- pinned_hop=payload.pinned_hop,
- pin_identity_claim=payload.pin_identity_claim,
- )
+ return payload.with_payload(result)
return result
diff --git a/core/handlers/model_hub/provenance.py b/core/handlers/model_hub/provenance.py
index 3dc1499ba..f6da0bed5 100644
--- a/core/handlers/model_hub/provenance.py
+++ b/core/handlers/model_hub/provenance.py
@@ -731,6 +731,10 @@ class TurnTrace:
# Vibey: the hosted tools the turn's first resolution froze, with each
# search tool's executor order. Written once; settings apply next turn.
hosted_tools: Optional[TurnHostedTools] = None
+ # The processing tier the turn's first resolution asked for (``"fast"`` or
+ # None, fast_mode.py). Written once; a Session's change applies next turn.
+ speed: Optional[str] = None
+ speed_recorded: bool = False
# Vibey: per Source, the identity digest the turn's native content is bound
# to, claimed by its first admitted pinned request. Each entry is written once.
pinned_identities: dict[str, str] = field(default_factory=dict)
@@ -1393,6 +1397,16 @@ class TurnCorrelationRegistry:
trace = self._traces.get(normalized)
return trace.hosted_tools if trace is not None else None
+ def turn_speed(self, turn_id: Optional[str]) -> Optional[str]:
+ """The processing tier a turn's first resolution asked for; None for standard or an untracked turn."""
+
+ normalized = str(turn_id or "").strip()
+ if not normalized:
+ return None
+ with self._lock:
+ trace = self._traces.get(normalized)
+ return trace.speed if trace is not None else None
+
def live_hosted_turn(
self, *, backend: str, token: str, request_metadata: Mapping[str, str] | None,
) -> tuple[str, TurnHostedTools | None] | None:
@@ -1669,6 +1683,7 @@ class TurnCorrelationRegistry:
turn_id: str,
route: PreparedGatewayRoute,
hosted_tools: TurnHostedTools | None = None,
+ speed: Optional[str] = None,
) -> bool:
trace = self._traces.setdefault(
turn_id,
@@ -1703,6 +1718,9 @@ class TurnCorrelationRegistry:
trace.gateway_model_id = route.resolved_model_id
if trace.hosted_tools is None:
trace.hosted_tools = hosted_tools
+ if not trace.speed_recorded:
+ trace.speed = speed
+ trace.speed_recorded = True
return True
def prepare_gateway_turn(
@@ -1719,11 +1737,13 @@ class TurnCorrelationRegistry:
primary_origin: HopOrigin | None = None,
primary_identity: str | None = None,
hosted_tools: TurnHostedTools | None = None,
+ speed: str | None = None,
) -> str:
"""Register a route and return its legacy credential or explicit handle.
- ``hosted_tools`` is what a Vibey turn's first resolution froze; the
- turn keeps the first it is given.
+ ``hosted_tools`` is what a Vibey turn's first resolution froze, and
+ ``speed`` the processing tier it asked for; the turn keeps the first
+ it is given.
"""
with self._lock:
@@ -1766,6 +1786,7 @@ class TurnCorrelationRegistry:
turn_id=normalized_turn_id,
route=prepared,
hosted_tools=hosted_tools,
+ speed=speed,
)
return launch_token
@@ -1815,6 +1836,7 @@ class TurnCorrelationRegistry:
turn_id=route_turn_id,
route=prepared,
hosted_tools=hosted_tools,
+ speed=speed,
)
return launch_token
diff --git a/core/handlers/model_hub/request.py b/core/handlers/model_hub/request.py
index d0e756f57..bb5456a61 100644
--- a/core/handlers/model_hub/request.py
+++ b/core/handlers/model_hub/request.py
@@ -35,6 +35,7 @@ class ModelHubRequest(dict[str, Any]):
primary_origin: HopOrigin | None = None,
pinned_hop: tuple[str, str | None] | None = None,
pin_identity_claim: Callable[[str, bool], bool] | None = None,
+ speed: str | None = None,
) -> None:
super().__init__(payload)
self.protocol = protocol
@@ -51,6 +52,18 @@ class ModelHubRequest(dict[str, Any]):
# content may go there under it. A turn's first claim binds the
# identity; a continuation needs one already bound.
self.pin_identity_claim = pin_identity_claim
+ # The turn's processing tier: ``"fast"`` asks each attempt for its
+ # vendor's fast tier where that exact hop offers one (fast_mode.py).
+ self.speed = speed
+
+ def with_payload(self, payload: Mapping[str, Any]) -> "ModelHubRequest":
+ """The same request metadata over another body."""
+
+ return ModelHubRequest(
+ payload, protocol=self.protocol, headers=self.headers,
+ primary_origin=self.primary_origin, pinned_hop=self.pinned_hop,
+ pin_identity_claim=self.pin_identity_claim, speed=self.speed,
+ )
_OPAQUE_FIELDS = frozenset({"signature", "thoughtSignature", "thought_signature", "encrypted_content"})
@@ -119,11 +132,7 @@ def without_opaque_history(request: Mapping[str, Any]) -> Mapping[str, Any]:
if field in payload:
payload[field] = _plain_history(payload[field])
if isinstance(request, ModelHubRequest):
- return ModelHubRequest(
- payload, protocol=request.protocol, headers=request.headers,
- primary_origin=request.primary_origin, pinned_hop=request.pinned_hop,
- pin_identity_claim=request.pin_identity_claim,
- )
+ return request.with_payload(payload)
return payload
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 3d53eb9cb..8285f6e91 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -15,7 +15,7 @@ from contextlib import asynccontextmanager
from dataclasses import dataclass, replace
from datetime import datetime, timedelta, timezone
from pathlib import Path
-from typing import Any, Awaitable, Callable, Collection, Iterable, Literal, Mapping, NamedTuple, Optional, Protocol, cast
+from typing import Any, Awaitable, Callable, Collection, Final, Iterable, Literal, Mapping, NamedTuple, Optional, Protocol, cast
from sqlalchemy import func, literal_column, select
@@ -235,6 +235,7 @@ from .provenance import (
produce_turn_outcome,
)
from .opaque_provenance import OpaqueProvenanceRegistry, filter_opaque_history
+from .fast_mode import FAST_SPEED, FastModeCatalog, load_fast_mode_catalog
from .request import ModelHubRequest, without_opaque_history
from .reasoning_tiers import catalog_wire_efforts, rederive_persisted_tiers, resolve_reasoning_tiers
from .stream_wire import ProtocolSSEState, ProtocolUsageReport
@@ -841,6 +842,30 @@ class _InvocationUnsupported(_InvocationPlanChanged):
self.reason = reason
+_FAST_REFUSAL_STATUSES = frozenset({400, 403, 429})
+
+
+def _fast_tier_refused(outcome: Optional[RawCallOutcome]) -> bool:
+ """A failed call refused before any output, as a vendor answers a fast tier it will not grant.
+
+ The vendors give that refusal no code of its own (Anthropic answers 429
+ ``rate_limit_error`` without usage credits), so any such refusal of a fast
+ attempt earns one standard retry; the retry's own outcome is classified.
+ """
+
+ return (
+ outcome is not None
+ and not outcome.stream_started
+ and outcome.http_status in _FAST_REFUSAL_STATUSES
+ )
+
+
+def _with_body_fields(request: Mapping[str, Any], fields: Mapping[str, Any]) -> Mapping[str, Any]:
+ """The request with these top-level body fields set, its metadata kept."""
+
+ payload = {**request, **fields}
+ return request.with_payload(payload) if isinstance(request, ModelHubRequest) else payload
+
def _pinned_hop(request: Any, backend: str) -> tuple[str, str | None] | None:
"""The exact (Source, model) a Vibey request is pinned to (``x-avibe-pin-source``), if any."""
@@ -1608,6 +1633,9 @@ class ModelHubService:
lambda _backend, _source: True
)
self._mutation_lock = asyncio.Lock()
+ # Which (Source, model) attempts offer a vendor's fast tier; read off the
+ # loop when a fast request arrives, rebuilt only when models.dev changes.
+ self._fast_mode_catalog = FastModeCatalog()
self._oauth_start_tasks: dict[
tuple[str, str, OAuthChannel], asyncio.Task[dict]
] = {}
@@ -5938,6 +5966,7 @@ class ModelHubService:
config = self.store.load()
return self._agent_payload(
config, self._agent(config, backend), live_recovery=self.recovery.annotations(config),
+ fast_catalog=self._load_fast_mode_catalog(),
)
async def read_agent_sources(self, backend: str) -> dict:
@@ -5949,7 +5978,11 @@ class ModelHubService:
config = await asyncio.to_thread(self.store.load)
agent = self._agent(config, backend)
live_recovery = self.recovery.annotations(config)
- return await asyncio.to_thread(self._agent_payload, config, agent, live_recovery=live_recovery)
+ return await asyncio.to_thread(
+ lambda: self._agent_payload(
+ config, agent, live_recovery=live_recovery, fast_catalog=self._load_fast_mode_catalog(),
+ )
+ )
async def set_agent_chain(self, backend: str, model_id: object, payload: object) -> dict:
if (
@@ -6162,7 +6195,13 @@ class ModelHubService:
def _agent_payload(
self, config: ModelHubConfig, agent: ModelHubAgentSupplyConfig,
*, live_recovery: Mapping[str, SourceRecoveryAnnotation] | None = None,
+ fast_catalog: FastModeCatalog | None = None,
) -> dict:
+ """``fast_catalog`` is a freshly read fast-tier index, from a caller off the loop.
+
+ Without one, the payload uses the index last read, which takes no I/O:
+ mutation responses are built on the controller loop.
+ """
backend = cast(BackendName, agent.backend)
hidden = self._hidden_retired_model_ids(agent)
builtin_models = (
@@ -6200,6 +6239,15 @@ class ModelHubService:
}
for model_id, model_resolution in model_resolutions.items()
]
+ # A Direct Agent's turns never reach the gateway that applies the fast tier.
+ if agent.mode != "hub":
+ fast_catalog = None
+ elif fast_catalog is None:
+ fast_catalog = self._fast_mode_catalog
+ fast_models = {
+ model.id: fast_catalog is not None and self._offers_fast_mode(backend, model_resolutions[model.id], fast_catalog)
+ for model in menu_models
+ }
# Only Hub turns reach the evidence; a Direct Agent's menu is the backend's own.
effort_menus = {
model.id: (
@@ -6301,7 +6349,8 @@ class ModelHubService:
"model_supply": model_supply if agent.mode == "hub" else None,
"named_agents": named_agents,
"catalog_models": [
- {**model, "effort_menu": effort_menus[model["id"]]} for model in self._catalog_models_payload(agent)
+ {**model, "effort_menu": effort_menus[model["id"]], "fast_mode": fast_models.get(model["id"], False)}
+ for model in self._catalog_models_payload(agent)
],
"builtin_models": builtin_models,
}
@@ -6571,8 +6620,9 @@ class ModelHubService:
def list_agents(self) -> list[dict]:
config = self.store.load()
live_recovery = self.recovery.annotations(config)
+ fast_catalog = self._load_fast_mode_catalog()
return [
- self._agent_payload(config, config.agents[backend], live_recovery=live_recovery)
+ self._agent_payload(config, config.agents[backend], live_recovery=live_recovery, fast_catalog=fast_catalog)
for backend in MODEL_HUB_BACKENDS
]
@@ -7146,6 +7196,24 @@ class ModelHubService:
return False
return self.hosted_evidence().unsupported(source, model_id, feature)
+ @staticmethod
+ def _offers_fast_mode(backend: BackendName, resolution: ModelHubTurnResolution, catalog: FastModeCatalog) -> bool:
+ """Whether a turn on this menu model would reach its vendor's fast tier on the hop that normally serves it.
+
+ The first candidate hop is the one a turn starts on; a fallback to a hop
+ without the tier runs at the standard tier. OpenCode's shared server
+ names no turn on its requests, so its turns carry no Session's choice.
+ """
+
+ hop = next(
+ (hop for hop in resolution.candidate_hops if hop.source is not None and hop.model_id is not None),
+ None,
+ )
+ if hop is None:
+ return False
+ protocol = hop.source.protocol if backend == "vibey" else _FIXED_BACKEND_PROTOCOLS.get(backend)
+ return catalog.body_for(hop.source, hop.model_id, protocol) is not None
+
def _effort_menu(
self, backend: BackendName, model: ModelHubBackendModelConfig, resolution: ModelHubTurnResolution, now: datetime
) -> dict:
@@ -10849,6 +10917,7 @@ class ModelHubService:
on_admitted: Callable[[int], None] | None = None,
recovery_request: RecoveryRequest | None = None,
hosted: HostedContent = HostedContent(),
+ fast_catalog: FastModeCatalog | None = None,
) -> InvokeHandle:
while True:
await self._mutation_lock.acquire()
@@ -10950,6 +11019,12 @@ class ModelHubService:
identity=identity,
registry=self.opaque_provenance,
)
+ if fast_catalog is not None:
+ # Read on this final snapshot: a hop gains the fast tier only
+ # where its exact Source and model offer one.
+ fast_body = fast_catalog.body_for(source, model_id, getattr(request, "protocol", None))
+ if fast_body is not None:
+ attempt_request = _with_body_fields(attempt_request, fast_body)
if self._engine_synced:
if recovery_request is not None and recovery_request.expired:
raise _RecoveryWindowClosed
@@ -10991,7 +11066,13 @@ class ModelHubService:
on_admitted: Callable[[int], None] | None = None,
recovery_request: RecoveryRequest | None = None,
hosted: HostedContent = HostedContent(),
+ fast_catalog: FastModeCatalog | None = None,
) -> tuple[InvokeHandle, Optional[RawCallOutcome], asyncio.CancelledError | None]:
+ """``fast_catalog`` puts each attempt that offers it on its vendor's fast tier
+ (docs/plans/fast-mode.md); a fast attempt refused before any output is
+ retried once on the same hop at the standard tier, and only that retry's
+ outcome reaches classification."""
+
acquired_handle: InvokeHandle | None = None
generation: int | None = None
@@ -11038,6 +11119,7 @@ class ModelHubService:
on_admitted=admitted,
recovery_request=recovery_request,
hosted=hosted,
+ fast_catalog=fast_catalog,
)
except InvokeCancelledError as cancelled:
await meter_observed(cancelled.observed, None)
@@ -11082,8 +11164,51 @@ class ModelHubService:
self.recovery.release(source.id, generation)
raise cancelled
+ if (
+ fast_catalog is not None
+ and cancelled is None
+ and _fast_tier_refused(outcome)
+ and fast_catalog.body_for(source, model_id, getattr(request, "protocol", None)) is not None
+ ):
+ # The fast tier is an upgrade, not a requirement: an account without
+ # it (no usage credits, an organization that disabled it, its own
+ # rate limit) is still served at the standard tier, and the refusal
+ # never reads as the Source failing.
+ logger.info(
+ "Model Hub fast tier refused before output; retrying at the standard tier",
+ extra={"source_id": source.id, "model_id": model_id, "http_status": outcome.http_status},
+ )
+ self.recovery.release(source.id, generation)
+ return await self._invoke(
+ source=source,
+ model_id=model_id,
+ request=request,
+ stream=stream,
+ backend=backend,
+ requested_model_id=requested_model_id,
+ excluded_source_ids=excluded_source_ids,
+ excluded_hops=excluded_hops,
+ supply_channel=supply_channel,
+ exact_retry=True,
+ on_admitted=on_admitted,
+ recovery_request=recovery_request,
+ hosted=hosted,
+ )
return handle, outcome, cancelled
+ async def _fast_mode_catalog_for(self, request: Mapping[str, Any]) -> FastModeCatalog | None:
+ """The fast-tier index for a request that asks for one, else None."""
+
+ if getattr(request, "speed", None) != FAST_SPEED:
+ return None
+ return await asyncio.to_thread(self._load_fast_mode_catalog)
+
+ def _load_fast_mode_catalog(self) -> FastModeCatalog:
+ """Read the fast-tier index and keep it for payloads built on the loop. Reads files: off the loop only."""
+
+ self._fast_mode_catalog = load_fast_mode_catalog()
+ return self._fast_mode_catalog
+
async def _settle_cancelled_attempt(
self,
*,
@@ -11258,6 +11383,7 @@ class ModelHubService:
raise ModelHubError(
"hosted_content_unpinned", status=422, turn_outcome=REQUEST_NONFALLBACK_TURN_OUTCOME,
)
+ fast_catalog = await self._fast_mode_catalog_for(request)
engine_prepared = False
# An entirely unsupported Google request must not reconcile the engine
# or custody. Supported hops drain the journal in demand preparation.
@@ -11425,6 +11551,7 @@ class ModelHubService:
on_admitted=admitted,
recovery_request=recovery_request,
hosted=hosted,
+ fast_catalog=fast_catalog,
)
except _InvocationUnsupported as skipped:
if pinned_hop is not None:
@@ -11501,6 +11628,7 @@ class ModelHubService:
on_admitted=admitted,
recovery_request=recovery_request,
hosted=hosted,
+ fast_catalog=fast_catalog,
)
except _InvocationPlanChanged:
if attempt_observer is not None:
diff --git a/core/handlers/model_hub/turn_gateway.py b/core/handlers/model_hub/turn_gateway.py
index d6753cf53..f85ffb5a7 100644
--- a/core/handlers/model_hub/turn_gateway.py
+++ b/core/handlers/model_hub/turn_gateway.py
@@ -598,6 +598,7 @@ class ModelHubTurnGateway:
primary_origin: HopOrigin | None = None,
primary_identity: str | None = None,
hosted_tools: TurnHostedTools | None = None,
+ speed: str | None = None,
) -> tuple[str, str]:
if backend not in MODEL_HUB_BACKENDS:
raise ModelHubError("mapping_target_unavailable", status=409)
@@ -647,6 +648,7 @@ class ModelHubTurnGateway:
primary_origin=primary_origin,
primary_identity=primary_identity,
hosted_tools=hosted_tools,
+ speed=speed,
)
except PreparedGatewayRouteConflict:
raise ModelHubError("mapping_target_unavailable", status=409) from None
@@ -1231,6 +1233,7 @@ class ModelHubTurnGateway:
)
if pin_source_id else None
),
+ speed=self.correlation.turn_speed(terminalizer.turn_id),
),
stream=stream,
supply_channel="hub",
diff --git a/core/workbench_prefs.py b/core/workbench_prefs.py
index dc4b49d95..0bbee27a0 100644
--- a/core/workbench_prefs.py
+++ b/core/workbench_prefs.py
@@ -29,3 +29,21 @@ def set_background_work_banner_enabled(enabled: bool, *, db_path: Path | None =
value = bool(enabled)
set_state_meta(BACKGROUND_WORK_BANNER_KEY, value, db_path=db_path)
return value
+
+
+# Whether a new Web Session starts with fast mode on (docs/plans/fast-mode.md):
+# the last choice made in a Web model picker. Default OFF.
+FAST_MODE_DEFAULT_KEY = "workbench.fast_mode_default"
+
+
+def get_fast_mode_default(*, db_path: Path | None = None) -> bool:
+ """Whether new Web Sessions start with fast mode on. Absent/malformed → OFF."""
+ raw = get_state_meta(FAST_MODE_DEFAULT_KEY, db_path=db_path)
+ return raw if isinstance(raw, bool) else False
+
+
+def set_fast_mode_default(enabled: bool, *, db_path: Path | None = None) -> bool:
+ """Persist the new-Session fast-mode default. Returns the stored boolean."""
+ value = bool(enabled)
+ set_state_meta(FAST_MODE_DEFAULT_KEY, value, db_path=db_path)
+ return value
diff --git a/docs/plans/fast-mode.md b/docs/plans/fast-mode.md
new file mode 100644
index 000000000..0c03de9d3
--- /dev/null
+++ b/docs/plans/fast-mode.md
@@ -0,0 +1,108 @@
+# Fast mode
+
+Status: owner-approved design, 2026-10-30. The menu uses option B: a Fast
+toggle beside the effort heading, with a hover explanation. The trigger uses
+mark ②: a slim light-amber bolt beside the chevron.
+
+## Goal
+
+OpenAI and Anthropic each sell a faster processing tier for some models: the
+same model, more output tokens per second, a higher price. A user can turn it
+on for a Session from the Web model picker and turn it off at any time. The
+closed picker shows a small mark while the Session runs fast. A new Web Session
+starts with the choice the user made last.
+
+- OpenAI calls it Fast mode, formerly priority processing. A Responses or Chat
+ Completions request sets `service_tier: "priority"`. ChatGPT plans offer it to
+ Codex as the "Fast" service tier, which uses more of the plan's quota.
+- Anthropic calls it fast mode: a Messages request sets `speed: "fast"` on
+ Claude Opus 5.5, and on 5 and 4.8 with a beta header. Claude subscriptions pay
+ for it from usage credits only.
+
+## Contract
+
+### Intent
+
+- A Session stores its processing tier in its row's `metadata.speed`: `"fast"`,
+ or absent for the standard tier. The Session payload exposes it as top-level
+ `speed` (`"fast"` or `null`). `POST /api/sessions` accepts `speed`, and so does
+ `PATCH /api/sessions/<id>`, including on the fixed main Session. A fork copies
+ the source Session's metadata, so it inherits the tier with the model and effort.
+- The remembered default is a global Workbench preference,
+ `state_meta["workbench.fast_mode_default"]`, read and written through
+ `/api/workbench/prefs` as `fast_mode_default`. The Web picker writes it on
+ every toggle, and the Web new-session composer starts from it. Sessions
+ created by IM, Tasks, Watches and `vibe agent run` start at the standard tier:
+ those surfaces show no mark, so they never pay more unseen.
+- Dispatch copies the Session row onto the turn's context. `resolve_model_hub_launch`
+ reads the tier from there and passes it to the Hub router, which records it on
+ the gateway turn the launch prepares (`TurnTrace.speed`). The turn keeps the
+ first value it is given, like its hosted tools, so a change applies from the
+ next turn.
+
+### Where the tier applies
+
+The gateway reads the turn's tier for each request it can attribute to a turn
+and carries it on `ModelHubRequest.speed`. Each attempt adds the vendor's field
+only where its exact `(Source, model)` offers the tier
+(`core/handlers/model_hub/fast_mode.py`):
+
+- the model's first-party vendor, by `vibe/data/model_vendors.json` family
+ prefix, is OpenAI or Anthropic, and the Source is that vendor's own upstream:
+ an API key on its official endpoint, or its subscription held by the Model Hub
+ (not a `native_cli` Source, whose requests never reach the gateway);
+- the request speaks the Source's protocol, so the tier is never reached through
+ a translation;
+- the vendor's models.dev entry for that model names the field under
+ `experimental.modes.fast.provider.body`. The entry's body must be exactly the
+ vendor's one field (`service_tier` for OpenAI, `speed` for Anthropic); any
+ other body is not applied. The engine adds the beta header the Anthropic
+ model needs. The catalog is the cached copy, read off the controller loop and
+ rebuilt only when that copy changes. Reading it never fetches.
+
+A fallback to a hop without the tier runs at the standard tier. OpenCode's
+shared server names no turn on its requests, so its turns never carry a
+Session's tier. Direct-mode Agents never reach the gateway. For both, the
+picker reports fast mode as not offered.
+
+### Refusal
+
+A vendor refuses the fast tier without a code of its own. For example,
+Anthropic answers an account without usage credits with 429
+`rate_limit_error`. So a fast attempt that fails with 400, 403 or 429 before any
+output is retried once on the same hop at the standard tier. Only that retry's
+outcome is classified, so a refused tier never cools down a healthy Source. A
+real rate limit costs one extra immediate request before it is classified as
+usual.
+
+### Picker
+
+- The Hub Agent read states, on each catalog model, whether a turn on it would
+ reach the fast tier on the hop that normally serves it (`fast_mode`). The model
+ menu remembers these per backend, beside the model labels
+ (`avibe.fast-models.v1`).
+- The compact picker's Fast toggle sits beside the effort heading. Its hover and
+ focus tooltip says what it does. While fast mode is on, a touch screen shows
+ the same line under the efforts. On a model without the tier, the toggle keeps
+ the Session's choice but is disabled, and the trigger shows no mark.
+- The trigger's mark, a slim bolt in light amber, sits beside the chevron,
+ outside the parts a narrow row drops. It shows only while the Session asks for
+ the fast tier and its model would get it.
+
+## Not in this change
+
+- Per-turn cost estimates. The tooltip says the price is higher; the
+ multiplier differs by vendor and plan.
+- Fast mode for Direct-mode Agents, OpenCode, and the IM settings surfaces.
+- Recording the served tier in usage records. The response's `service_tier` or
+ `usage.speed` says which tier ran.
+
+## Validation
+
+- Scenario tests: `MH-FAST-001` (a fast Session's turn reaches the hop that
+ offers the tier, and only that hop), `MH-FAST-002` (a refused tier is served
+ at the standard tier, and its Source stays routable), and `MH-FAST-003` (the
+ menu marks the models that would run fast).
+- Units: the hop rule (`tests/test_model_hub_fast_mode.py`), the Session field
+ and its dispatch read, the preference, the picker, and the new-session flow.
+- Browser: the mark stays visible on a crowded 320px phone row.
diff --git a/docs/plans/model-hub-contracts/backend-model.schema.json b/docs/plans/model-hub-contracts/backend-model.schema.json
index e6d0a3d5a..4c592af22 100644
--- a/docs/plans/model-hub-contracts/backend-model.schema.json
+++ b/docs/plans/model-hub-contracts/backend-model.schema.json
@@ -108,6 +108,10 @@
}
}
}
+ },
+ "fast_mode": {
+ "type": "boolean",
+ "description": "Server-derived on Agent reads, accepted and dropped on write like effort_menu. Whether a turn on this model reaches its vendor's fast tier on the hop that normally serves it (docs/plans/fast-mode.md): that hop's Source is the model's first-party vendor's own upstream and the vendor's models.dev entry names the tier's request field. False for an Agent in Direct mode and for OpenCode, whose requests name no turn."
}
}
}
diff --git a/modules/agents/model_hub.py b/modules/agents/model_hub.py
index 831a95e44..756055be5 100644
--- a/modules/agents/model_hub.py
+++ b/modules/agents/model_hub.py
@@ -20,7 +20,9 @@ from urllib.parse import urlsplit
from config import paths
from config.atomic_io import write_atomic
from config.v2_config import MODEL_HUB_BACKENDS, ModelHubConfig, ModelHubSourceConfig
+from core.agent_session_context import session_speed_for_context
from core.handlers.model_hub.capability_evidence import identity_digest
+from core.handlers.model_hub.fast_mode import normalized_speed
from core.ordered_worker import OrderedWorker
from core.handlers.model_hub.classification import ResolutionDecision
from core.handlers.model_hub.events import (
@@ -333,6 +335,8 @@ async def resolve_model_hub_launch(
router = getattr(controller, "model_hub_runtime", None)
resolver = getattr(router, "resolve", None)
if callable(resolver):
+ # The Session this turn runs in may ask for its vendors' fast tier.
+ speed = session_speed_for_context(context)
if turn_id is None:
# Only the Turn's own dispatch task is found this way; a caller resolving
# from another task (Vibey's later model calls) names its Turn itself.
@@ -347,6 +351,7 @@ async def resolve_model_hub_launch(
process_scope=process_scope,
turn_id=turn_id,
**snapshot,
+ **({"speed": speed} if speed is not None else {}),
)
except ModelHubError as exc:
failure = _localized_launch_error(
@@ -905,6 +910,7 @@ class ModelHubRuntimeRouter:
hosted_tools: TurnHostedTools | None = None,
request_scoped: bool | None = None,
primary_identity: str | None = None,
+ speed: str | None = None,
) -> tuple[str, str]:
if self.turn_gateway is not None:
return await self.turn_gateway.endpoint(
@@ -924,6 +930,7 @@ class ModelHubRuntimeRouter:
**({"primary_origin": primary_origin} if primary_origin is not None else {}),
**({"primary_identity": primary_identity} if primary_identity is not None else {}),
**({"hosted_tools": hosted_tools} if hosted_tools is not None else {}),
+ **({"speed": speed} if speed is not None else {}),
)
await self.service._ensure_engine_synced()
status = await self.service._engine_call(self.service.adapter.start())
@@ -1202,7 +1209,10 @@ class ModelHubRuntimeRouter:
process_scope: Optional[str] = None,
turn_id: Optional[str] = None,
config: ModelHubConfig | None = None,
+ speed: Optional[str] = None,
) -> ModelHubLaunch:
+ """``speed`` is the turn's processing tier (``"fast"`` or None), kept on the gateway turn it opens."""
+
requested_model = str(requested_model or "").strip()
config = config if config is not None else self.service.store.load()
if backend == "vibey" and (
@@ -1333,6 +1343,7 @@ class ModelHubRuntimeRouter:
primary_identity=identity,
# The executor endpoint runs only what the turn froze.
hosted_tools=frozen,
+ speed=normalized_speed(speed),
)
if self.turn_gateway is None:
prefix = await self._source_prefix(source.id)
diff --git a/storage/agent_session_rows.py b/storage/agent_session_rows.py
index 08b583f71..f38602f93 100644
--- a/storage/agent_session_rows.py
+++ b/storage/agent_session_rows.py
@@ -45,6 +45,18 @@ INBOX_SESSION_VISIBILITIES: tuple[str, ...] = ("foreground", "system")
PRIVATE_AGENT_RUN_SCOPE_TYPE = "private_agent_run"
SESSION_PROJECT_BASE_METADATA_KEY = "project_base"
+#: ``metadata_json`` key holding a Session's processing tier: ``"fast"`` asks its
+#: turns for the vendor's fast tier (docs/plans/fast-mode.md); absent is standard.
+SESSION_SPEED_METADATA_KEY = "speed"
+SESSION_SPEED_FAST = "fast"
+
+
+def session_speed(metadata: Any) -> str | None:
+ """The processing tier a Session's metadata names: ``"fast"``, or None for standard."""
+
+ if not isinstance(metadata, dict):
+ return None
+ return SESSION_SPEED_FAST if metadata.get(SESSION_SPEED_METADATA_KEY) == SESSION_SPEED_FAST else None
logger = logging.getLogger(__name__)
diff --git a/storage/workbench_sessions_service.py b/storage/workbench_sessions_service.py
index 0f60f8c6d..d574129ae 100644
--- a/storage/workbench_sessions_service.py
+++ b/storage/workbench_sessions_service.py
@@ -37,9 +37,12 @@ from storage.agent_session_rows import (
TERMINAL_SWITCH_BACKEND,
insert_superseded_native_snapshot,
SESSION_PROJECT_BASE_METADATA_KEY,
+ SESSION_SPEED_FAST,
+ SESSION_SPEED_METADATA_KEY,
WORKSPACE_NOTICE_SESSION_ID,
create_agent_session_row,
new_session_id,
+ session_speed,
normalize_workdir,
normalize_session_project_base,
reserve_write_lock,
@@ -108,6 +111,7 @@ def _row_to_payload(
) -> dict[str, Any]:
metadata = _load_metadata(row.get("metadata_json"))
metadata.pop(SESSION_PROJECT_BASE_METADATA_KEY, None)
+ speed = session_speed(metadata)
if not include_local_details:
metadata = {}
return {
@@ -125,6 +129,8 @@ def _row_to_payload(
"agent_variant": row.get("agent_variant"),
"model": row.get("model"),
"reasoning_effort": row.get("reasoning_effort"),
+ # The Session's processing tier: "fast" or null (standard).
+ "speed": speed,
"status": row.get("status"),
"visibility": row.get("visibility") or "foreground",
"pinned": bool(row.get("pinned")),
@@ -156,6 +162,17 @@ def _dumps_metadata(metadata: dict[str, Any]) -> str:
return json.dumps(metadata)
+def _apply_session_speed(metadata: dict[str, Any], speed: Any) -> None:
+ """Write a Session's processing tier: ``"fast"``, or None/empty for the standard tier."""
+
+ if speed is None or speed == "":
+ metadata.pop(SESSION_SPEED_METADATA_KEY, None)
+ elif speed == SESSION_SPEED_FAST:
+ metadata[SESSION_SPEED_METADATA_KEY] = SESSION_SPEED_FAST
+ else:
+ raise ValueError(f"invalid session speed: {speed!r}")
+
+
def _has_runtime_management_access(context: AuthorizationContext) -> bool:
return context.can_manage_instance
@@ -465,6 +482,7 @@ def create_session(
workdir: Optional[str] = None,
visibility: str = "foreground",
metadata: Optional[dict[str, Any]] = None,
+ speed: Optional[str] = None,
authorization_context: AuthorizationContext | Mapping[str, Any] | None = None,
user_context: Any = None,
workdir_prepared: bool = False,
@@ -619,6 +637,8 @@ def create_session(
metadata_payload = {"created_via": "workbench"}
if metadata:
metadata_payload.update(metadata)
+ if speed is not None:
+ _apply_session_speed(metadata_payload, speed)
session_id = str(session_id or new_session_id(conn))
if scope_id is None:
@@ -654,7 +674,7 @@ MAIN_SESSION_METADATA_KEY = "kind"
MAIN_SESSION_METADATA_VALUE = "main"
MAIN_SESSION_WORKDIR_DIRNAME = "main"
MAIN_SESSION_WORKDIR_COMPONENT = "owner"
-MAIN_SESSION_UPDATABLE_FIELDS = frozenset({"model", "reasoning_effort", "title", "pinned"})
+MAIN_SESSION_UPDATABLE_FIELDS = frozenset({"model", "reasoning_effort", "speed", "title", "pinned"})
class MainSessionArchivedError(PermissionError):
@@ -991,6 +1011,7 @@ def update_session(
agent_variant: Any = _UNSET,
model: Any = _UNSET,
reasoning_effort: Any = _UNSET,
+ speed: Any = _UNSET,
visibility: Any = _UNSET,
pinned: Any = _UNSET,
scope_id: Any = _UNSET,
@@ -1037,6 +1058,7 @@ def update_session(
("agent_variant", agent_variant),
("model", model),
("reasoning_effort", reasoning_effort),
+ ("speed", speed),
("visibility", visibility),
("pinned", pinned),
("scope_id", scope_id),
@@ -1261,6 +1283,9 @@ def update_session(
values["model"] = model or None
if reasoning_effort is not _UNSET:
values["reasoning_effort"] = reasoning_effort or None
+ if speed is not _UNSET:
+ _apply_session_speed(existing_metadata, speed)
+ values["metadata_json"] = _dumps_metadata(existing_metadata)
if visibility is not _UNSET:
visibility_value = str(visibility or "").strip()
# ASSIGNABLE, not the full storage vocabulary: ``system`` is a runtime
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index ad846e6bf..92e1cf957 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -2248,6 +2248,24 @@ scenarios:
kind: compatibility
layer: scenario
test: tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py::test_mh_effort_001_unknown_capability_preserves_intent_and_turn_completes
+ - id: MH-FAST-001
+ name: A fast Session's turn asks its hop for the vendor's fast tier only where that hop offers one
+ status: covered
+ kind: routing
+ layer: scenario
+ test: tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py::test_mh_fast_001_session_speed_reaches_the_hop_that_offers_it
+ - id: MH-FAST-002
+ name: A fast tier refused before output is served at the standard tier and its Source stays routable
+ status: covered
+ kind: recovery
+ layer: scenario
+ test: tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py::test_mh_fast_002_refused_fast_tier_is_served_at_the_standard_tier
+ - id: MH-FAST-003
+ name: Each Hub menu model says whether a turn on it would reach the fast tier on its serving hop
+ status: covered
+ kind: projection
+ layer: scenario
+ test: tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py::test_mh_fast_003_model_menu_marks_the_models_a_turn_would_run_fast_on
- id: MH-TURN-RESULT-001
name: All terminal outcomes are closed schema-valid provenance products
status: covered
diff --git a/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py b/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
index a8b866927..ab8d278a6 100644
--- a/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
+++ b/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
@@ -1534,3 +1534,150 @@ def test_opencode_refuses_an_unlisted_model_its_retained_route_cannot_address(
}
asyncio.run(exercise())
+
+
+def _cache_fast_modes(fast_models: dict[str, dict[str, str]]) -> None:
+ """A models.dev copy in this test's state dir whose OpenAI entries offer these fast-tier bodies."""
+
+ from vibe import models_dev_catalog
+
+ models_dev_catalog._write_cache({
+ "url": models_dev_catalog.DEFAULT_MODELS_DEV_URL,
+ "fetched_at": 0,
+ "catalog": {
+ "openai": {
+ "models": {
+ model_id: {"experimental": {"modes": {"fast": {"provider": {"body": body}}}}}
+ for model_id, body in fast_models.items()
+ }
+ }
+ },
+ })
+
+
+ ("session_speed", "catalog_body", "expected_tier"),
+ [
+ ("fast", {"service_tier": "priority"}, "priority"),
+ # A Session at the standard tier sends nothing extra.
+ (None, {"service_tier": "priority"}, None),
+ # A model its vendor offers no fast tier for runs at the standard tier.
+ ("fast", None, None),
+ # A catalog entry asking for any other field is not applied.
+ ("fast", {"service_tier": "priority", "store": "true"}, None),
+ ],
+ ids=["fast", "standard-session", "model-without-fast", "foreign-field"],
+)
+def test_mh_fast_001_session_speed_reaches_the_hop_that_offers_it(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ session_speed: str | None,
+ catalog_body: dict[str, str] | None,
+ expected_tier: str | None,
+) -> None:
+ """MH-FAST-001: a fast Session's turn asks its hop for the vendor's fast tier only where that hop offers one."""
+
+ from vibe import models_dev_catalog
+
+ monkeypatch.setattr(models_dev_catalog, "_refresh_in_background", lambda: False)
+ model_id = _requested_model("codex")
+ _cache_fast_modes({model_id: catalog_body} if catalog_body is not None else {})
+
+ async def exercise() -> None:
+ adapter = AdapterBoundaryFake(
+ [AdapterResult(RawOutcomeKind.SUCCESS, status=200, body=b'{"ok":true}')]
+ )
+ store = MemoryStore(_config(_source("src_chatgpt1", kind="subscription")))
+ service = _service(
+ tmp_path, store, adapter, now=lambda: datetime(2026, 10, 30, tzinfo=timezone.utc),
+ )
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ controller = SimpleNamespace(model_hub_runtime=router)
+ context = SimpleNamespace(platform_specific={
+ "agent_session_target": {"id": "ses_fast", "metadata": {"speed": session_speed} if session_speed else {}},
+ })
+ try:
+ launch = await resolve_model_hub_launch(
+ controller, "codex", model_id,
+ process_scope="scenario-fast", context=context, turn_id="turn_fast",
+ )
+ status, body = await _post_turn(
+ launch,
+ endpoint="responses",
+ payload={"model": launch.runtime_model, "input": [], "stream": False},
+ )
+ assert (status, body) == (200, b'{"ok":true}')
+ assert [request.get("service_tier") for request in adapter.requests] == [expected_tier]
+ finally:
+ await gateway.close()
+
+ asyncio.run(exercise())
+
+
+def test_mh_fast_002_refused_fast_tier_is_served_at_the_standard_tier(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """MH-FAST-002: an upstream that refuses the fast tier before output serves the turn at the standard tier, and its Source stays routable."""
+
+ from vibe import models_dev_catalog
+
+ monkeypatch.setattr(models_dev_catalog, "_refresh_in_background", lambda: False)
+ model_id = _requested_model("codex")
+ _cache_fast_modes({model_id: {"service_tier": "priority"}})
+
+ async def exercise() -> None:
+ adapter = AdapterBoundaryFake([
+ # Anthropic answers an account without usage credits this way; any
+ # refusal before output gets the same single standard retry.
+ AdapterResult(RawOutcomeKind.HTTP_ERROR, status=429, code="rate_limit_error"),
+ AdapterResult(RawOutcomeKind.SUCCESS, status=200, body=b'{"ok":true}'),
+ ])
+ store = MemoryStore(_config(_source("src_chatgpt1", kind="subscription")))
+ service = _service(
+ tmp_path, store, adapter, now=lambda: datetime(2026, 10, 30, tzinfo=timezone.utc),
+ )
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ launch = await router.resolve(
+ "codex", model_id, process_scope="scenario-fast", turn_id="turn_fast", speed="fast",
+ )
+ status, body = await _post_turn(
+ launch,
+ endpoint="responses",
+ payload={"model": launch.runtime_model, "input": [], "stream": False},
+ )
+ assert (status, body) == (200, b'{"ok":true}')
+ assert [(source, request.get("service_tier")) for (source, _model, _origin), request in zip(
+ adapter.invocations, adapter.requests,
+ )] == [("src_chatgpt1", "priority"), ("src_chatgpt1", None)]
+ assert store.load().sources[0].state.status != "cooldown"
+ finally:
+ await gateway.close()
+
+ asyncio.run(exercise())
+
+
+def test_mh_fast_003_model_menu_marks_the_models_a_turn_would_run_fast_on(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """MH-FAST-003: each Hub menu model says whether a turn on it would reach the fast tier on its serving hop."""
+
+ from vibe import models_dev_catalog
+
+ monkeypatch.setattr(models_dev_catalog, "_refresh_in_background", lambda: False)
+ fast_model = _requested_model("codex")
+ _cache_fast_modes({fast_model: {"service_tier": "priority"}})
+ store = MemoryStore(_config(_source("src_chatgpt1", kind="subscription")))
+ service = _service(
+ tmp_path, store, AdapterBoundaryFake([]), now=lambda: datetime(2026, 10, 30, tzinfo=timezone.utc),
+ )
+
+ menu = {row["id"]: row["fast_mode"] for row in service.get_agent_sources("codex")["catalog_models"]}
+ assert menu[fast_model] is True
+ assert any(offered is False for model, offered in menu.items() if model != fast_model)
+ # OpenCode's shared server names no turn on its requests, so no Session choice reaches it.
+ assert not any(row["fast_mode"] for row in service.get_agent_sources("opencode")["catalog_models"])
diff --git a/tests/test_model_hub_api.py b/tests/test_model_hub_api.py
index 54beeb80f..214434a55 100644
--- a/tests/test_model_hub_api.py
+++ b/tests/test_model_hub_api.py
@@ -2513,6 +2513,7 @@ def test_backend_catalog_add_edit_and_runtime_refresh(
"routeable": True,
# Server-derived like ``locked``: a client may send back the row it read, and the read states it again.
"effort_menu": {"omitted": [], "not_on": {}},
+ "fast_mode": False,
}
if backend == "opencode":
added["native_protocol"] = "openai_responses"
@@ -3019,6 +3020,7 @@ def test_backend_catalog_add_validates_supplier_echo_and_stores_draft_literally(
"locked": False,
"routeable": True,
"effort_menu": {"omitted": [], "not_on": {}},
+ "fast_mode": False,
}
before = store.config.to_payload()
@@ -5059,6 +5061,35 @@ async def _idle_mode_guard(backends, *, external_processes=True):
yield verify_idle
+def test_agent_payload_built_on_the_loop_reads_no_fast_mode_catalog(tmp_path, monkeypatch):
+ """A mode switch answers with the Agent payload built on the controller loop; the fast-tier index it
+ shows is the one last read, never a file read there (fast_mode.py)."""
+
+ import threading
+
+ from core.handlers.model_hub import service as service_module
+
+ loop_reads = []
+
+ def load():
+ loop_reads.append(threading.current_thread() is threading.main_thread())
+ return service_module.FastModeCatalog()
+
+ monkeypatch.setattr(service_module, "load_fast_mode_catalog", load)
+ service, store, _adapter = _service(tmp_path)
+ service.migration_home = tmp_path / "native-home"
+ service.migration_guard = _idle_mode_guard
+ store.config.agents["claude"].mode = "direct"
+
+ switched = asyncio.run(service.set_agent_mode("claude", "hub"))
+
+ assert switched["mode"] == "hub"
+ assert True not in loop_reads
+ # A synchronous read, which the read routes serve off the loop, refreshes it.
+ service.get_agent_sources("claude")
+ assert loop_reads[-1:] == [True]
+
+
def test_direct_to_hub_changes_only_mode(tmp_path):
service, store, _adapter = _service(tmp_path)
service.migration_home = tmp_path / "native-home"
diff --git a/tests/test_model_hub_fast_mode.py b/tests/test_model_hub_fast_mode.py
new file mode 100644
index 000000000..8e89deaa3
--- /dev/null
+++ b/tests/test_model_hub_fast_mode.py
@@ -0,0 +1,77 @@
+"""Which Model Hub attempts may ask for a vendor's fast tier (core/handlers/model_hub/fast_mode.py)."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from core.handlers.model_hub.fast_mode import FastModeCatalog
+
+_VENDOR_MAP = {
+ "families": [
+ {"prefix": "gpt-", "vendor_id": "openai"},
+ {"prefix": "claude-", "vendor_id": "anthropic"},
+ {"prefix": "grok-", "vendor_id": "xai"},
+ ]
+}
+
+
+def _fast(body: dict) -> dict:
+ return {"experimental": {"modes": {"fast": {"provider": {"body": body}}}}}
+
+
+_CATALOG = FastModeCatalog.from_models_dev(
+ {
+ "openai": {"models": {"gpt-5.6-sol": _fast({"service_tier": "priority"}), "gpt-5.4-mini": {}}},
+ "anthropic": {"models": {"claude-opus-5-5": {**_fast({"speed": "fast"}), "id": "claude-opus-5-5"}}},
+ "xai": {"models": {"grok-5": _fast({"service_tier": "priority"})}},
+ },
+ _VENDOR_MAP,
+)
+
+
+def _source(vendor="openai", protocol="openai_responses", kind="api_key", base_url=None, supply_channel="hub"):
+ return SimpleNamespace(vendor=vendor, protocol=protocol, kind=kind, base_url=base_url, supply_channel=supply_channel)
+
+
+ ("source", "model", "request_protocol", "expected"),
+ [
+ (_source(), "gpt-5.6-sol", "openai_responses", {"service_tier": "priority"}),
+ (_source(protocol="openai_chat"), "gpt-5.6-sol", "openai_chat", {"service_tier": "priority"}),
+ (_source(base_url="https://api.openai.com/v1"), "gpt-5.6-sol", "openai_responses", {"service_tier": "priority"}),
+ (_source(kind="subscription"), "gpt-5.6-sol", "openai_responses", {"service_tier": "priority"}),
+ (_source("anthropic", "anthropic", "subscription"), "claude-opus-5-5", "anthropic", {"speed": "fast"}),
+ # A dated or context-tagged spelling of a listed model is the same model.
+ (_source("anthropic", "anthropic"), "claude-opus-5-5[1m]", "anthropic", {"speed": "fast"}),
+ # A relay or custom endpoint may front any deployment.
+ (_source(base_url="https://relay.example/v1"), "gpt-5.6-sol", "openai_responses", None),
+ # The native CLI's own login never reaches the gateway.
+ (_source(kind="subscription", supply_channel="native_cli"), "gpt-5.6-sol", "openai_responses", None),
+ # Never translated across protocols to reach a fast tier.
+ (_source(), "gpt-5.6-sol", "anthropic", None),
+ # A model its vendor lists without a fast tier, and one another vendor makes.
+ (_source(), "gpt-5.4-mini", "openai_responses", None),
+ (_source(), "claude-opus-5-5", "openai_responses", None),
+ # Only the vendors whose field Avibe knows.
+ (_source("xai", "openai_responses"), "grok-5", "openai_responses", None),
+ ],
+)
+def test_fast_tier_is_offered_only_by_the_models_own_vendor_upstream(source, model, request_protocol, expected):
+ assert _CATALOG.body_for(source, model, request_protocol) == expected
+
+
+def test_catalog_entries_asking_for_other_fields_are_not_applied():
+ catalog = FastModeCatalog.from_models_dev(
+ {
+ "openai": {"models": {
+ "gpt-a": _fast({"service_tier": "priority", "store": True}),
+ "gpt-b": _fast({"reasoning": {"mode": "pro"}}),
+ "gpt-c": _fast({"service_tier": ""}),
+ }},
+ "anthropic": {"models": {"claude-x": _fast({"service_tier": "priority"})}},
+ },
+ _VENDOR_MAP,
+ )
+ assert catalog.bodies == {}
diff --git a/tests/test_workbench_prefs_api.py b/tests/test_workbench_prefs_api.py
index 8641be7d6..3703339f7 100644
--- a/tests/test_workbench_prefs_api.py
+++ b/tests/test_workbench_prefs_api.py
@@ -34,6 +34,23 @@ def test_banner_pref_api_round_trip(monkeypatch, tmp_path):
] is True
+def test_new_session_fast_mode_default_round_trip(monkeypatch, tmp_path):
+ """Where a new Web Session's fast mode starts: the last picker choice, OFF until one is made."""
+
+ monkeypatch.setenv("AVIBE_HOME", str(tmp_path))
+ _save_config(tmp_path)
+ from storage.importer import ensure_sqlite_state
+
+ ensure_sqlite_state()
+
+ assert api.get_workbench_prefs()["fast_mode_default"] is False
+ assert api.set_workbench_prefs(fast_mode_default=True)["fast_mode_default"] is True
+ # Another toggle leaves it alone, and it leaves the other toggle alone.
+ prefs = api.set_workbench_prefs(background_work_banner_enabled=False)
+ assert (prefs["fast_mode_default"], prefs["background_work_banner_enabled"]) == (True, False)
+ assert api.set_workbench_prefs(fast_mode_default=False)["fast_mode_default"] is False
+
+
def test_banner_pref_get_route_defaults_on(monkeypatch, tmp_path):
monkeypatch.setenv("AVIBE_HOME", str(tmp_path))
_save_config(tmp_path)
diff --git a/tests/test_workbench_session_defaults.py b/tests/test_workbench_session_defaults.py
index eac37893a..d495cba3e 100644
--- a/tests/test_workbench_session_defaults.py
+++ b/tests/test_workbench_session_defaults.py
@@ -200,3 +200,30 @@ def test_folderless_project_session_snapshots_process_cwd(engine, tmp_path, monk
)
assert session["workdir"] == str(tmp_path)
+
+
+def test_session_speed_is_stored_with_the_session_and_read_by_dispatch(engine, tmp_path):
+ """A Session's fast mode survives create and update and reaches the turns dispatched from its row."""
+
+ from types import SimpleNamespace
+
+ from core.agent_session_context import session_speed_for_context
+
+ def dispatched(session):
+ # Dispatch copies the Session row onto the turn's context (internal_server).
+ return session_speed_for_context(SimpleNamespace(platform_specific={"agent_session_target": session}))
+
+ created = _project_with_default(engine, tmp_path)
+ with engine.begin() as conn:
+ session = workbench_sessions_service.create_session(
+ conn, scope_id=created["scope_id"], agent_backend="", speed="fast",
+ )
+ assert (session["speed"], dispatched(session)) == ("fast", "fast")
+ standard = workbench_sessions_service.update_session(conn, session["id"], speed=None)
+ assert (standard["speed"], dispatched(standard)) == (None, None)
+ # Another edit leaves the choice alone.
+ fast = workbench_sessions_service.update_session(conn, session["id"], speed="fast")
+ renamed = workbench_sessions_service.update_session(conn, session["id"], title="Renamed")
+ assert (fast["speed"], renamed["speed"], dispatched(renamed)) == ("fast", "fast", "fast")
+ with pytest.raises(ValueError):
+ workbench_sessions_service.update_session(conn, session["id"], speed="turbo")
diff --git a/ui/e2e/home-media/fixture.tsx b/ui/e2e/home-media/fixture.tsx
index 3f3af6200..ec7a5e771 100644
--- a/ui/e2e/home-media/fixture.tsx
+++ b/ui/e2e/home-media/fixture.tsx
@@ -159,6 +159,8 @@ window.fetch = async (input, init) => {
if (control.messageMode === 'rejected') return reply({ state: 'retired', dispatch_error: 'dispatch_failed' }, 502);
return reply({ id: 'message-1', type: 'user', ...body }, 201);
}
+ // The new-session composer starts from the remembered fast-mode default.
+ if (path === '/api/workbench/prefs') return reply({ ok: true, background_work_banner_enabled: true, fast_mode_default: false });
if (path === '/api/asr/status') return reply({ available: true, max_file_bytes: 25_000_000 });
if (path === '/api/cloud/token') return reply({ error: 'fixture local ASR only' }, 503);
if (path === '/api/asr/transcribe') {
diff --git a/ui/e2e/workbench-general/composer-route-trigger.spec.ts b/ui/e2e/workbench-general/composer-route-trigger.spec.ts
index 59a88f26f..8fe44337b 100644
--- a/ui/e2e/workbench-general/composer-route-trigger.spec.ts
+++ b/ui/e2e/workbench-general/composer-route-trigger.spec.ts
@@ -9,12 +9,15 @@ import { open, serveProduct } from './support';
const SESSION_ID = 'route-trigger-fixture';
const EFFORTS = ['low', 'medium', 'high', 'xhigh'].map((value) => ({ value, label: value }));
-async function serveChat(page: Page, { running, agentName = 'pm-claude' }: { running: boolean; agentName?: string }) {
+async function serveChat(
+ page: Page,
+ { running, agentName = 'pm-claude', fast = false }: { running: boolean; agentName?: string; fast?: boolean },
+) {
const denied = await serveProduct(page);
const session = {
id: SESSION_ID, scope_id: 'fixture', project_id: 'proj-1', title: 'Route trigger',
agent_id: 'agt-pm', agent_name: agentName, agent_backend: 'claude', model: 'claude-opus-4-7',
- reasoning_effort: 'xhigh', status: 'active', agent_status: running ? 'running' : 'idle', pinned: false,
+ reasoning_effort: 'xhigh', speed: fast ? 'fast' : null, status: 'active', agent_status: running ? 'running' : 'idle', pinned: false,
workdir: '/fixture/work', native_session_id: 'native-1', metadata: {},
created_at: '2026-10-26T00:00:00Z', updated_at: '2026-10-26T00:00:00Z',
};
@@ -34,8 +37,16 @@ async function serveChat(page: Page, { running, agentName = 'pm-claude' }: { run
await page.route(`**/api/sessions/${SESSION_ID}/activity**`, (route) => route.fulfill({ json: { groups: [] } }));
await page.route(`**/api/inbox/${SESSION_ID}/read`, (route) => route.fulfill({ json: { ok: true } }));
await page.route('**/api/asr/status', (route) => route.fulfill({ json: { available: true } }));
- // The closed trigger names the model by its catalog label.
- await page.route('**/api/models/agents/**', (route) => route.fulfill({ json: { ok: false } }));
+ // The closed trigger names the model by its catalog label. A fast route reads
+ // Model Hub's catalog, which says the model reaches its vendor's fast tier.
+ await page.route('**/api/models/agents/**', (route) => route.fulfill({ json: fast
+ ? { ok: true, agent: { backend: 'claude', mode: 'hub', catalog_models: [{
+ id: 'claude-opus-4-7', origin: 'builtin', display_name: 'Claude Opus 4.7', models_dev_id: null,
+ context_window: null, max_output_tokens: null, input_modalities: [], output_modalities: [],
+ supports_tools: null, supports_reasoning: true, reasoning_efforts: ['low', 'medium', 'high', 'xhigh'],
+ locked: false, routeable: true, effort_menu: { omitted: [], not_on: {} }, fast_mode: true,
+ }] } }
+ : { ok: false } }));
await page.route('**/api/claude/models', (route) => route.fulfill({ json: {
ok: true,
models: ['claude-opus-4-7', 'claude-sonnet-4-6'],
@@ -142,3 +153,23 @@ test('a name wider than a crowded phone row keeps its beginning and ends in an e
await page.screenshot({ path: 'e2e/.artifacts/workbench-general/shots/composer-route-trigger-long-name.png' });
expect(denied).toEqual([]);
});
+
+test('a route that runs fast keeps its mark beside the chevron when a crowded phone row drops detail', async ({ page }) => {
+ const denied = await serveChat(page, { running: true, fast: true });
+ await page.setViewportSize({ width: 320, height: 760 });
+ await open(page, `/chat/${SESSION_ID}`);
+ await expect(page.getByRole('button', { name: 'Stop', exact: true })).toBeVisible();
+ await page.locator('main [contenteditable="true"]').last().click();
+ await page.keyboard.type('Run the next step after this one');
+ await expect(page.getByRole('button', { name: 'Send to queue', exact: true })).toBeVisible();
+
+ const trigger = page.locator('main').getByRole('button', { name: /pm-claude/ });
+ const mark = trigger.locator('[data-fast-mark]');
+ await expect(mark).toBeVisible();
+ // The mark says the route costs more: detail gives way, the mark does not.
+ const parts = trigger.locator('[data-route-trigger-parts]');
+ expect(await shownDetails(parts)).not.toContain('effort');
+ expect(inside((await mark.boundingBox())!, (await trigger.boundingBox())!)).toBe(true);
+ await page.screenshot({ path: 'e2e/.artifacts/workbench-general/shots/composer-route-trigger-fast.png' });
+ expect(denied).toEqual([]);
+});
diff --git a/ui/e2e/workbench-general/geometry.spec.ts b/ui/e2e/workbench-general/geometry.spec.ts
index 7b2b14cac..3d3a8f8ac 100644
--- a/ui/e2e/workbench-general/geometry.spec.ts
+++ b/ui/e2e/workbench-general/geometry.spec.ts
@@ -283,6 +283,11 @@ test.describe('workbench home geometry', () => {
if (url.pathname === '/api/dock') return route.fulfill({ json: {
dock: { order: ['files', 'terminal', 'editor', 'library'], pins: [] },
} });
+ if (url.pathname === '/api/macos/login-session') return route.fulfill({ json: { ok: true, state: 'healthy' } });
+ // The home composer starts a new Session at the remembered fast-mode default.
+ if (url.pathname === '/api/workbench/prefs') return route.fulfill({ json: {
+ ok: true, background_work_banner_enabled: true, fast_mode_default: false,
+ } });
if (inheritedReads.has(url.pathname)) return route.fallback();
unknown.push(`${request.method()} ${request.url()}`);
return route.abort();
diff --git a/ui/e2e/workbench-general/sidebar-floating.spec.ts b/ui/e2e/workbench-general/sidebar-floating.spec.ts
index 8ae02221d..43cf9ce73 100644
--- a/ui/e2e/workbench-general/sidebar-floating.spec.ts
+++ b/ui/e2e/workbench-general/sidebar-floating.spec.ts
@@ -39,6 +39,10 @@ async function serveProduct(page: Page, lang: Lang = 'en') {
dock: { order: ['files', 'terminal', 'editor', 'library'], pins: [] },
} });
if (path === '/api/macos/login-session') return route.fulfill({ json: { ok: true, state: 'healthy' } });
+ // The home composer starts a new Session at the remembered fast-mode default.
+ if (path === '/api/workbench/prefs') return route.fulfill({ json: {
+ ok: true, background_work_banner_enabled: true, fast_mode_default: false,
+ } });
if (inheritedReads.has(path)) return route.fallback();
audit.unknown.push(`${request.method()} ${request.url()}`);
return route.abort();
diff --git a/ui/src/components/Workbench.tsx b/ui/src/components/Workbench.tsx
index ecee202be..45165f165 100644
--- a/ui/src/components/Workbench.tsx
+++ b/ui/src/components/Workbench.tsx
@@ -184,6 +184,8 @@ export const Workbench: React.FC = () => {
disabled={ns.sending}
align="end"
triggerClassName="max-w-[min(60vw,360px)]"
+ speed={ns.speed}
+ onSpeedChange={ns.setSpeed}
/>
}
onSend={send}
diff --git a/ui/src/components/settings/models/types.ts b/ui/src/components/settings/models/types.ts
index c45e0099c..6383b22c5 100644
--- a/ui/src/components/settings/models/types.ts
+++ b/ui/src/components/settings/models/types.ts
@@ -245,7 +245,11 @@ export type BackendModel = {
export type EffortMenu = { omitted: string[]; not_on: Record<string, string[]> };
/** A catalog row as the model picker reads it. */
-export type PickerCatalogModel = BackendModel & { effort_menu?: EffortMenu };
+export type PickerCatalogModel = BackendModel & {
+ effort_menu?: EffortMenu;
+ /** Whether a turn on this model reaches its vendor's fast tier on the hop that normally serves it. */
+ fast_mode?: boolean;
+};
/** The model picker's read of one backend's catalog (`GET /api/models/agents/<backend>/models`). */
export type PickerAgentCatalog = Pick<AgentSupply, 'backend' | 'mode'> & { catalog_models?: PickerCatalogModel[] | null };
diff --git a/ui/src/components/workbench/AgentRoutePicker.test.tsx b/ui/src/components/workbench/AgentRoutePicker.test.tsx
index 8f5adefe2..d860520ce 100644
--- a/ui/src/components/workbench/AgentRoutePicker.test.tsx
+++ b/ui/src/components/workbench/AgentRoutePicker.test.tsx
@@ -45,6 +45,8 @@ vi.mock('../../context/ApiContext', async (importOriginal) => ({
let catalogReasoning: Record<string, { value: string; label: string }[]> = {};
let catalogMenus: Record<string, { omitted: string[]; not_on: Record<string, string[]> }> = {};
let catalogLabels: Record<string, string> = {};
+// The models a Hub catalog says run at their vendor's fast tier.
+let catalogFast: string[] = [];
// How many catalog reads were made, and whether the next ones wait to be answered.
let catalogReads = 0;
let deferReads = false;
@@ -62,6 +64,7 @@ vi.mock('../../lib/backendModels', async (importOriginal) => ({
modelLabels: Record<string, string>;
reasoningOptions: Record<string, { value: string; label: string }[]>;
effortMenus?: Record<string, { omitted: string[]; not_on: Record<string, string[]> }>;
+ fastModels?: string[];
hubUnread?: true;
catalogRefreshPending: boolean;
}) => void,
@@ -72,7 +75,9 @@ vi.mock('../../lib/backendModels', async (importOriginal) => ({
modelLabels: catalogLabels,
reasoningOptions: catalogReasoning,
// As the real loader answers: only a Hub catalog carries effort menus.
- ...(hubUnread ? { hubUnread: true as const } : hubMode === 'hub' ? { effortMenus: catalogMenus } : {}),
+ ...(hubUnread
+ ? { hubUnread: true as const }
+ : hubMode === 'hub' ? { effortMenus: catalogMenus, fastModels: catalogFast } : {}),
catalogRefreshPending: false,
});
if (deferReads) pendingReads.push(answer);
@@ -598,10 +603,85 @@ describe('AgentRoutePicker compact presentation', () => {
cleanup();
catalogReasoning = {};
catalogMenus = {};
+ catalogFast = [];
+ window.localStorage.clear();
sourceNames = null;
hubMode = 'direct';
});
+ // An owner of both the route and its speed, applying each pick at once.
+ const FastOwner: React.FC<{
+ initial: AgentRouteValue;
+ initialSpeed?: 'fast' | null;
+ onSpeed: (speed: 'fast' | null) => void;
+ }> = ({ initial, initialSpeed = null, onSpeed }) => {
+ const [route, setRoute] = useState<AgentRouteValue>(initial);
+ const [speed, setSpeed] = useState<'fast' | null>(initialSpeed);
+ return (
+ <MemoryRouter>
+ <AgentRoutePicker
+ presentation="compact"
+ value={route}
+ agents={AGENTS}
+ onChange={(patch) => setRoute((prev) => ({ ...prev, ...patch }))}
+ speed={speed}
+ onSpeedChange={(next) => {
+ setSpeed(next);
+ onSpeed(next);
+ }}
+ />
+ </MemoryRouter>
+ );
+ };
+
+ it("judges Fast on the Agent's model for a route that names none", async () => {
+ // A Session that materialized its Agent at the first turn keeps no model of its own.
+ hubMode = 'hub';
+ catalogReasoning = { sonnet: [{ value: 'low', label: 'low' }], opus: [{ value: 'low', label: 'low' }] };
+ catalogFast = ['sonnet'];
+ const user = userEvent.setup();
+ render(<FastOwner initial={{ ...CLAUDE_ROUTE, model: null }} initialSpeed="fast" onSpeed={vi.fn()} />);
+ await openMenu(user);
+ // The claude Agent's default model is sonnet, which runs fast.
+ expect((screen.getByRole('button', { name: 'chat.picker.fast' }) as HTMLButtonElement).disabled).toBe(false);
+ expect(screen.queryByLabelText('chat.picker.fastOn')).not.toBeNull();
+ });
+
+ it('offers Fast only where the model runs fast, marks the trigger while it does, and keeps the choice across a model without it', async () => {
+ hubMode = 'hub';
+ catalogReasoning = { sonnet: [{ value: 'low', label: 'low' }], opus: [{ value: 'low', label: 'low' }] };
+ catalogFast = ['opus'];
+ const user = userEvent.setup();
+ const onSpeed = vi.fn();
+ render(<FastOwner initial={{ ...CLAUDE_ROUTE, model: 'opus' }} onSpeed={onSpeed} />);
+ const mark = () => screen.queryByLabelText('chat.picker.fastOn');
+ expect(mark()).toBeNull();
+
+ await openMenu(user);
+ const toggle = () => screen.getByRole('button', { name: 'chat.picker.fast' });
+ expect(toggle().getAttribute('aria-pressed')).toBe('false');
+ // Hover or focus explains what it does.
+ expect(screen.getByRole('tooltip').textContent).toContain('chat.picker.fastDescription');
+ await user.click(toggle());
+ expect(onSpeed).toHaveBeenLastCalledWith('fast');
+ expect(toggle().getAttribute('aria-pressed')).toBe('true');
+ expect(mark()).not.toBeNull();
+
+ // A model without a fast tier keeps the choice but neither runs fast nor offers the toggle.
+ await user.click(screen.getByRole('button', { name: /^sonnet/ }));
+ expect(mark()).toBeNull();
+ expect(toggle().getAttribute('aria-pressed')).toBe('true');
+ expect((toggle() as HTMLButtonElement).disabled).toBe(true);
+ expect(screen.getByRole('tooltip').textContent).toContain('chat.picker.fastUnavailable');
+
+ // Back on a model with one, the remembered choice runs fast again.
+ await user.click(screen.getByRole('button', { name: /^opus/ }));
+ expect(mark()).not.toBeNull();
+ await user.click(toggle());
+ expect(onSpeed).toHaveBeenLastCalledWith(null);
+ expect(mark()).toBeNull();
+ });
+
const effortGroup = () => within(screen.getByRole('radiogroup', { name: 'chat.picker.effort' }));
it('writes models and efforts from the first page and keeps Agents one level down', async () => {
diff --git a/ui/src/components/workbench/AgentRoutePicker.tsx b/ui/src/components/workbench/AgentRoutePicker.tsx
index 01330257e..151b77002 100644
--- a/ui/src/components/workbench/AgentRoutePicker.tsx
+++ b/ui/src/components/workbench/AgentRoutePicker.tsx
@@ -1,17 +1,22 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { useNavigate } from 'react-router-dom';
import { Check, ChevronDown, ChevronLeft, ChevronRight, Loader2, Plus, Search, Sparkles } from 'lucide-react';
import clsx from 'clsx';
import { useApi } from '../../context/ApiContext';
-import type { VibeAgentBrief } from '../../context/ApiContext';
+import type { SessionSpeed, VibeAgentBrief } from '../../context/ApiContext';
import { useInstanceAuthorization } from '../../context/InstanceAuthorizationContext';
import type { EffortMenu } from '../settings/models/types';
import { loadBackendModelsWithRefresh, modelOptionLabel, supersedesHubAnswer, useAddModelExit } from '../../lib/backendModels';
import { isEffortSupported, refusedSavedEffort, resolveEffortOptions } from '../../lib/effortOptions';
import { useSourceNames } from '../../lib/useSourceNames';
-import { rememberModelLabels, useRememberedModelLabel } from '../../lib/modelLabelMemory';
+import {
+ rememberFastModels,
+ rememberModelLabels,
+ useRememberedFastModel,
+ useRememberedModelLabel,
+} from '../../lib/modelLabelMemory';
import { useRouteSurfaceActive } from '../../lib/routeSurfaceActivity';
import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover';
import { ResponsiveMenu } from '../ui/responsive-menu';
@@ -74,6 +79,12 @@ interface AgentRoutePickerProps {
* Model Hub exit does not call it: Settings opens over this surface, and a
* host suspends under it with its draft intact, as it does for any visit. */
onNavigateAway?: () => void;
+ /** The route's processing tier (compact only, docs/plans/fast-mode.md). With
+ * ``onSpeedChange`` the menu offers the Fast toggle beside the effort, and the
+ * closed trigger marks a route that runs fast. Applied by the owner, like
+ * ``onChange``. */
+ speed?: SessionSpeed;
+ onSpeedChange?: (speed: SessionSpeed) => void;
}
type ReasoningOption = { value: string; label: string };
@@ -102,6 +113,8 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
presentation = 'columns',
modal,
onNavigateAway,
+ speed = null,
+ onSpeedChange,
}) => {
const { t } = useTranslation();
const api = useApi();
@@ -179,6 +192,16 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
// The closed trigger names the model as the menu does, from labels remembered
// across pickers and loads; the raw id stays one hover away.
const currentModelLabel = useRememberedModelLabel(backend, currentModel) ?? currentModel;
+ // Fast mode is the route's to ask for and the model's hop's to grant: the mark
+ // and the toggle follow whether this model would actually run fast, so asking
+ // on a model without it keeps the choice for the next model that has it.
+ const fastControls = compact && Boolean(onSpeedChange);
+ const fastOn = speed === 'fast';
+ // The model a turn runs on: the route's own, else its Agent's default, which a
+ // Session that materialized its Agent at the first turn keeps without copying.
+ const effectiveModel = currentModel || displayedAgent?.model || null;
+ const fastOffered = useRememberedFastModel(backend, effectiveModel, fastControls && (fastOn || open));
+ const fastActive = fastControls && fastOn && fastOffered;
const currentAgentLabel = displayedAgent?.display_name || currentAgent;
const triggerLabel = (routeIsDefault && defaultLabel) || currentAgentLabel || defaultLabel || t('chat.pickAgent');
const agentLabel = currentAgentLabel || defaultLabel || t('chat.pickAgent');
@@ -272,6 +295,8 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
setModelLabelsByBackend((prev) => ({ ...prev, [backend]: modelLabels ?? {} }));
// Closed pickers anywhere name their model from this answer.
rememberModelLabels(backend, modelLabels ?? {});
+ // An unread Hub says nothing about which models run fast.
+ if (!result.hubUnread) rememberFastModels(backend, result.fastModels ?? []);
},
() => {
loadedBackends.delete(backend);
@@ -510,11 +535,16 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
{/* In-flight feedback replaces the chevron rather than greying the menu:
the pick is already applied, so the user is watching a save, not
waiting for their click to take effect. */}
- {saving ? (
- <Loader2 className="ml-auto size-3 shrink-0 animate-spin text-muted" aria-label={t('common.saving')} />
- ) : (
- <ChevronDown className="ml-auto size-3 shrink-0 text-muted" />
- )}
+ <span className="ml-auto flex shrink-0 items-center gap-0.5">
+ {/* Outside the wrapping parts, so the mark never gives way: it says the
+ route costs more, which a narrow row must not hide. */}
+ {fastActive && <FastMark data-fast-mark="" aria-label={t('chat.picker.fastOn')} className="text-gold/60" />}
+ {saving ? (
+ <Loader2 className="size-3 shrink-0 animate-spin text-muted" aria-label={t('common.saving')} />
+ ) : (
+ <ChevronDown className="size-3 shrink-0 text-muted" />
+ )}
+ </span>
</Button>
);
@@ -612,9 +642,24 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
);
})}
</RouteColumn>
- {showEffortColumn && (
+ {(showEffortColumn || fastControls) && (
<div className="border-t border-border p-3">
- <div className="pb-2 text-[10px] font-bold uppercase tracking-[0.1em] text-muted">{t('chat.picker.effort')}</div>
+ <div className={clsx('flex items-center', showEffortColumn && 'pb-2')}>
+ <span className="text-[10px] font-bold uppercase tracking-[0.1em] text-muted">
+ {showEffortColumn ? t('chat.picker.effort') : t('chat.picker.speed')}
+ </span>
+ {fastControls && (
+ <FastToggle
+ on={fastOn}
+ offered={fastOffered}
+ active={fastActive}
+ disabled={loadingModels}
+ onToggle={() => onSpeedChange?.(fastOn ? null : 'fast')}
+ />
+ )}
+ </div>
+ {showEffortColumn && (
+ <>
{/* One tap per effort, wrapping when a model states many. Hints that
a column would print under each row are listed below instead. */}
<div
@@ -648,6 +693,15 @@ export const AgentRoutePicker: React.FC<AgentRoutePickerProps> = ({
</p>
) : null;
})}
+ </>
+ )}
+ {/* A touch screen has no hover for the toggle's explanation: it is
+ written out while the route runs fast. */}
+ {fastActive && (
+ <p className="pt-1.5 text-[10px] leading-snug text-muted [@media(hover:hover)]:hidden">
+ {t('chat.picker.fastCaption')}
+ </p>
+ )}
</div>
)}
</div>
@@ -869,3 +923,56 @@ const ModelName: React.FC<{ label: string }> = ({ label }) => {
</>
);
};
+
+// The fast-mode bolt: a slim filled glyph, quiet enough to sit beside the
+// chevron without competing with the route's name. Colour comes from the caller.
+const FAST_BOLT_PATH = 'M13.6 2.2 6.4 13.1h5l-1.5 8.7 7.7-11.4h-5.2z';
+
+const FastMark: React.FC<React.SVGProps<SVGSVGElement>> = ({ className, ...props }) => (
+ <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden={props['aria-label'] ? undefined : true} className={clsx('size-[11px] shrink-0', className)} {...props}>
+ <path d={FAST_BOLT_PATH} />
+ </svg>
+);
+
+// The Fast toggle beside the effort heading. Hover or focus explains it; a
+// model whose hop offers no fast tier keeps the choice but cannot change it here.
+const FastToggle: React.FC<{
+ on: boolean;
+ offered: boolean;
+ active: boolean;
+ disabled?: boolean;
+ onToggle: () => void;
+}> = ({ on, offered, active, disabled, onToggle }) => {
+ const { t } = useTranslation();
+ const tipId = useId();
+ return (
+ <span className="group/fast relative ml-auto">
+ <button
+ type="button"
+ aria-pressed={on}
+ aria-describedby={tipId}
+ disabled={disabled || !offered}
+ onClick={onToggle}
+ className={clsx(
+ 'inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-[11px] font-semibold transition-colors',
+ 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-cyan/60 disabled:cursor-not-allowed disabled:opacity-50',
+ active ? 'border-gold/30 bg-gold-soft text-gold-ink/80' : 'border-border text-muted hover:text-foreground',
+ )}
+ >
+ <FastMark className={active ? 'text-gold/60' : undefined} />
+ {t('chat.picker.fast')}
+ </button>
+ <span
+ id={tipId}
+ role="tooltip"
+ className="pointer-events-none absolute bottom-full right-0 z-50 mb-1.5 w-56 rounded-md bg-foreground px-2.5 py-2 text-[11px] leading-snug text-background opacity-0 shadow-md transition-opacity group-hover/fast:opacity-100 group-focus-within/fast:opacity-100"
+ >
+ <span className="block font-semibold">{t('chat.picker.fastTitle')}</span>
+ <span className="block">{t('chat.picker.fastDescription')}</span>
+ <span className="block text-background/65">
+ {offered ? t('chat.picker.fastScope') : t('chat.picker.fastUnavailable')}
+ </span>
+ </span>
+ </span>
+ );
+};
diff --git a/ui/src/components/workbench/ChatPage.tsx b/ui/src/components/workbench/ChatPage.tsx
index 929c25e49..6f4fe7fed 100644
--- a/ui/src/components/workbench/ChatPage.tsx
+++ b/ui/src/components/workbench/ChatPage.tsx
@@ -3662,6 +3662,7 @@ interface ChatRoutePickerProps {
// Read-only sessions never mount it — their header names the frozen route.
const ChatRoutePicker: React.FC<ChatRoutePickerProps> = ({ session, agents, defaultAgentName, onPatch, patchSaving, working }) => {
const { t } = useTranslation();
+ const api = useApi();
const defaultAgent = defaultAgentName ? agents.find((agent) => agent.name === defaultAgentName) : null;
// Mirrors update_session's guard. A session with a NATIVE conversation can
// still move to another backend: the server replaces the conversation and
@@ -3720,6 +3721,12 @@ const ChatRoutePicker: React.FC<ChatRoutePickerProps> = ({ session, agents, defa
isDefaultRoute={inheritsDefault}
triggerClassName="max-w-[min(60vw,360px)]"
align="end"
+ speed={session.speed ?? null}
+ onSpeedChange={(speed) => {
+ onPatch({ speed });
+ // The latest choice is where the next new Session starts.
+ void api.setFastModeDefault(speed === 'fast').catch(() => undefined);
+ }}
/>
);
};
diff --git a/ui/src/components/workbench/NewSessionSheet.tsx b/ui/src/components/workbench/NewSessionSheet.tsx
index bb2df1c92..987180c56 100644
--- a/ui/src/components/workbench/NewSessionSheet.tsx
+++ b/ui/src/components/workbench/NewSessionSheet.tsx
@@ -169,6 +169,8 @@ export const NewSessionSheet: React.FC<NewSessionSheetProps> = ({ open, onClose,
disabled={ns.sending}
align="end"
triggerClassName="max-w-[min(60vw,360px)]"
+ speed={ns.speed}
+ onSpeedChange={ns.setSpeed}
modal
onNavigateAway={close}
/>
diff --git a/ui/src/context/ApiContext.tsx b/ui/src/context/ApiContext.tsx
index 8fb2aa916..35f504c3d 100644
--- a/ui/src/context/ApiContext.tsx
+++ b/ui/src/context/ApiContext.tsx
@@ -76,7 +76,15 @@ export type ScopeSettingsPatchResult = {
// Global workbench toggles persisted server-side in state_meta. Currently just
// the background-work banner switch (spec req 2); read by ChatPage (to gate the
// banner) and the Harness page (the toggle card).
-export type WorkbenchPrefs = { ok?: boolean; background_work_banner_enabled: boolean };
+export type WorkbenchPrefs = {
+ ok?: boolean;
+ background_work_banner_enabled: boolean;
+ /** Whether a new Web Session starts with fast mode on: the last choice made in a model picker. */
+ fast_mode_default?: boolean;
+};
+
+/** A Session's processing tier: ``fast`` asks its turns for the vendor's fast tier; null is standard. */
+export type SessionSpeed = 'fast' | null;
// One backend's *global* instructions file, surfaced by the Global Prompts
// editor. ``backend`` is an agent backend id (claude / opencode / codex).
@@ -661,6 +669,8 @@ export type ApiContextType = {
getWorkbenchPrefs: () => Promise<WorkbenchPrefs>;
/** Persist the background-work banner global toggle; resolves to updated prefs. */
setBackgroundWorkBannerEnabled: (enabled: boolean) => Promise<WorkbenchPrefs>;
+ /** Persist whether new Web Sessions start with fast mode on; resolves to updated prefs. */
+ setFastModeDefault: (enabled: boolean) => Promise<WorkbenchPrefs>;
getBindCodes: () => Promise<any>;
createBindCode: (type: string, expiresAt?: string) => Promise<any>;
deleteBindCode: (code: string) => Promise<any>;
@@ -1060,6 +1070,8 @@ export type WorkbenchSession = {
agent_variant: string | null;
model: string | null;
reasoning_effort: string | null;
+ /** Optional because payloads cached by an older client predate the field. */
+ speed?: SessionSpeed;
status: string;
/** Storage projection, not a user preference: ``foreground`` = an ordinary chat,
* ``background`` = hidden and undelivered, ``system`` = a row the RUNTIME owns
@@ -1109,6 +1121,7 @@ export type WorkbenchSessionCreate = {
agent_variant?: string;
model?: string;
reasoning_effort?: string;
+ speed?: 'fast';
title?: string;
metadata?: Record<string, unknown>;
};
@@ -1122,6 +1135,7 @@ export type WorkbenchSessionUpdate = {
agent_variant: string;
model: string | null;
reasoning_effort: string | null;
+ speed: SessionSpeed;
pinned: boolean;
};
@@ -3743,6 +3757,22 @@ export const ApiProvider: React.FC<{ children: React.ReactNode }> = ({ children
);
return payloadJson;
},
+ setFastModeDefault: async (enabled) => {
+ // A remembered preference, written behind the pick it follows: a failure
+ // only leaves the next new Session on the previous default.
+ const { payloadJson } = await requestJson(
+ '/api/workbench/prefs',
+ {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ fast_mode_default: enabled }),
+ },
+ 'PUT /api/workbench/prefs',
+ { handleError: false, clearCache: false },
+ );
+ readCacheRef.current.delete('/api/workbench/prefs');
+ return payloadJson;
+ },
getBindCodes: () => getJson('/api/bind-codes'),
createBindCode: (type, expiresAt) => postJson('/api/bind-codes', { type, expires_at: expiresAt }),
deleteBindCode: (code) => deleteJson(`/api/bind-codes/${encodeURIComponent(code)}`),
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 71c1a6633..0365fbab7 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -5180,6 +5180,14 @@
"effortNotOn": "Not on {{sources}}",
"effortNotOnSome": "Not on some Sources",
"effortRefused": "No Source accepts it now · clear it under Models → Sources",
+ "speed": "Speed",
+ "fast": "Fast",
+ "fastOn": "Fast mode on",
+ "fastTitle": "Fast mode",
+ "fastDescription": "Same model, faster output, higher price.",
+ "fastScope": "Offered on some models and providers only",
+ "fastUnavailable": "Not offered for this model or provider",
+ "fastCaption": "Fast: faster output, higher price",
"newAgent": "New agent",
"addModel": "Add model",
"noModels": "No models found",
diff --git a/ui/src/i18n/zh.json b/ui/src/i18n/zh.json
index 01a03b43e..d19a0a230 100644
--- a/ui/src/i18n/zh.json
+++ b/ui/src/i18n/zh.json
@@ -5180,6 +5180,14 @@
"effortNotOn": "{{sources}} 不支持",
"effortNotOnSome": "部分供应商不支持",
"effortRefused": "当前没有供应商支持 · 可在模型 → 供应商中清除",
+ "speed": "速度",
+ "fast": "Fast",
+ "fastOn": "Fast 模式已开启",
+ "fastTitle": "Fast 模式",
+ "fastDescription": "同一个模型,输出更快,费用更高。",
+ "fastScope": "仅部分模型和服务商支持",
+ "fastUnavailable": "当前模型或服务商不支持",
+ "fastCaption": "Fast:输出更快,费用更高",
"newAgent": "新建 Agent",
"addModel": "添加模型",
"noModels": "未找到模型",
diff --git a/ui/src/lib/backendModels.test.ts b/ui/src/lib/backendModels.test.ts
index 8550ca6fc..33b1f3ae3 100644
--- a/ui/src/lib/backendModels.test.ts
+++ b/ui/src/lib/backendModels.test.ts
@@ -147,6 +147,7 @@ describe('fetchBackendModels in gateway mode', () => {
const api = { readModelHubAgentCatalogForModelPicker, claudeModels, codexModels, readOpencodeOptionsForModelPicker } as unknown as ApiContextType;
expect(await fetchBackendModels(api, 'vibey')).toEqual({
models: ['local-model'], modelLabels: { 'local-model': 'Local model' }, reasoningOptions: { 'local-model': [] }, effortMenus: {},
+ fastModels: [],
});
expect(readModelHubAgentCatalogForModelPicker).toHaveBeenCalledWith('vibey');
readModelHubAgentCatalogForModelPicker.mockResolvedValue(null);
@@ -175,7 +176,8 @@ describe('fetchBackendModels in gateway mode', () => {
supports_reasoning: true,
reasoning_efforts: ['low', 'high'],
}),
- model('beta'),
+ // A turn on beta would reach its vendor's fast tier.
+ { ...model('beta'), fast_mode: true },
],
}),
),
@@ -196,6 +198,7 @@ describe('fetchBackendModels in gateway mode', () => {
},
// No row states an effort menu, so nothing is left out or marked.
effortMenus: {},
+ fastModels: ['beta'],
});
});
@@ -362,6 +365,7 @@ describe('fetchBackendModels in gateway mode', () => {
modelLabels: {},
reasoningOptions: {},
effortMenus: {},
+ fastModels: [],
});
expect(codexModels).not.toHaveBeenCalled();
});
diff --git a/ui/src/lib/backendModels.ts b/ui/src/lib/backendModels.ts
index 59ff576e5..00595b3e7 100644
--- a/ui/src/lib/backendModels.ts
+++ b/ui/src/lib/backendModels.ts
@@ -22,6 +22,9 @@ export interface BackendModels {
* `effort_menu`): the efforts left out above, and by Source id the hops that
* refuse one the others still serve. Hub catalogs only. */
effortMenus?: Record<string, EffortMenu>;
+ /** The models a turn would run on at its vendor's fast tier (Model Hub's
+ * `fast_mode`). Hub catalogs only: a Direct backend offers none. */
+ fastModels?: string[];
/** True while a background remote-catalog refresh may produce a newer snapshot. */
catalogRefreshPending?: boolean;
/** Model Hub gave no answer (the read failed, or the server predates the read),
@@ -55,6 +58,7 @@ const hubCatalogModels = (agent: PickerAgentCatalog | null, backend: string): Ba
const modelLabels = Object.create(null) as Record<string, string>;
const reasoningOptions = Object.create(null) as Record<string, { value: string; label: string }[]>;
const effortMenus = Object.create(null) as Record<string, EffortMenu>;
+ const fastModels: string[] = [];
for (const id of models) {
const row = rows.get(id);
if (!row) continue;
@@ -69,8 +73,9 @@ const hubCatalogModels = (agent: PickerAgentCatalog | null, backend: string): Ba
? []
: row.reasoning_efforts.filter((effort) => !omitted.has(effort)).map((effort) => ({ value: effort, label: effort }));
if (row.effort_menu) effortMenus[id] = row.effort_menu;
+ if (row.fast_mode === true) fastModels.push(id);
}
- return { models, modelLabels, reasoningOptions, effortMenus };
+ return { models, modelLabels, reasoningOptions, effortMenus, fastModels };
};
/**
@@ -138,6 +143,15 @@ export async function fetchBackendModels(
* catalog, or Claude/Codex's cached catalog snapshot. OpenCode's live list is
* never read here — it may start OpenCode, and it carries no labels anyway.
*/
+/**
+ * The models a backend's turns would run on at their vendor's fast tier, read
+ * from Model Hub's persisted catalog only. A backend Hub does not serve, or
+ * whose catalog it cannot answer, offers none.
+ */
+export async function fetchBackendFastModels(api: ApiContextType, backend: string): Promise<string[]> {
+ return hubCatalogModels(await api.readModelHubAgentCatalogForModelPicker(backend), backend)?.fastModels ?? [];
+}
+
export async function fetchBackendModelLabels(
api: ApiContextType,
backend: string,
diff --git a/ui/src/lib/modelLabelMemory.test.ts b/ui/src/lib/modelLabelMemory.test.ts
index d9564a5e9..f04c3b2e5 100644
--- a/ui/src/lib/modelLabelMemory.test.ts
+++ b/ui/src/lib/modelLabelMemory.test.ts
@@ -89,3 +89,33 @@ describe('remembered model labels', () => {
expect(api.readOpencodeOptionsForModelPicker).not.toHaveBeenCalled();
});
});
+
+describe('remembered fast-tier models', () => {
+ const hubCatalog = (fast: string[]) => ({
+ backend: 'claude',
+ mode: 'hub',
+ catalog_models: ['claude-opus-5-5', 'claude-sonnet-5-5'].map((id) => ({
+ id, origin: 'builtin', display_name: null, models_dev_id: null, context_window: null, max_output_tokens: null,
+ input_modalities: [], output_modalities: [], supports_tools: null, supports_reasoning: null, reasoning_efforts: [],
+ locked: false, routeable: true, fast_mode: fast.includes(id),
+ })),
+ });
+
+ it('paints from a stored answer, then reads it again once per load since routing may have moved', async () => {
+ // Stored while the route went through a relay: no fast tier then.
+ window.localStorage.setItem('avibe.fast-models.v1', JSON.stringify({ claude: [] }));
+ api.readModelHubAgentCatalogForModelPicker.mockResolvedValue(hubCatalog(['claude-opus-5-5']));
+ const { useRememberedFastModel } = await freshMemory();
+
+ const { result, rerender } = renderHook(({ wanted }) => useRememberedFastModel('claude', 'claude-opus-5-5', wanted), {
+ initialProps: { wanted: false },
+ });
+ expect(result.current).toBe(false);
+ expect(api.readModelHubAgentCatalogForModelPicker).not.toHaveBeenCalled();
+
+ rerender({ wanted: true });
+ await waitFor(() => expect(result.current).toBe(true));
+ rerender({ wanted: true });
+ expect(api.readModelHubAgentCatalogForModelPicker).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/ui/src/lib/modelLabelMemory.ts b/ui/src/lib/modelLabelMemory.ts
index 9b477b2ab..b613f33f4 100644
--- a/ui/src/lib/modelLabelMemory.ts
+++ b/ui/src/lib/modelLabelMemory.ts
@@ -1,7 +1,7 @@
import { useEffect, useSyncExternalStore } from 'react';
import { useApi } from '../context/ApiContext';
-import { fetchBackendModelLabels } from './backendModels';
+import { fetchBackendFastModels, fetchBackendModelLabels } from './backendModels';
// Friendly model names ("Opus 5.5") for closed pickers, which otherwise only
// know the raw id the route stores. Every catalog answer a picker already reads
@@ -82,3 +82,71 @@ export function useRememberedModelLabel(backend: string, model: string | null |
}, [api, backend, model, label]);
return label;
}
+
+// Which models run at their vendor's fast tier, for a closed picker's fast-mode
+// mark: it shows only while the Session asks for the fast tier AND its model
+// would get it. Remembered from every catalog answer a picker reads, so the mark
+// paints from the first frame. Unlike a label, the answer follows routing, which
+// Settings or another client may have changed since it was stored: a picker that
+// needs it reads Model Hub's persisted catalog once per backend per page load.
+
+const FAST_STORAGE_KEY = 'avibe.fast-models.v1';
+
+type FastByBackend = Record<string, string[]>;
+
+function readStoredFast(): FastByBackend {
+ try {
+ const raw = typeof window !== 'undefined' ? window.localStorage.getItem(FAST_STORAGE_KEY) : null;
+ const parsed = raw ? (JSON.parse(raw) as unknown) : null;
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+ const out = Object.create(null) as FastByBackend;
+ for (const [backend, models] of Object.entries(parsed as Record<string, unknown>)) {
+ if (Array.isArray(models) && models.every((model) => typeof model === 'string')) out[backend] = models;
+ }
+ return out;
+ } catch {
+ return {};
+ }
+}
+
+let fastByBackend: FastByBackend | null = null;
+const fastListeners = new Set<() => void>();
+const fastReadThisLoad = new Set<string>();
+
+const currentFast = (): FastByBackend => (fastByBackend ??= readStoredFast());
+
+/** Record a backend's complete answer of fast-tier models, replacing what was known for it. */
+export function rememberFastModels(backend: string, models: readonly string[]): void {
+ if (!backend) return;
+ fastReadThisLoad.add(backend);
+ const next = Object.assign(Object.create(null), currentFast()) as FastByBackend;
+ next[backend] = [...models];
+ fastByBackend = next;
+ try {
+ window.localStorage.setItem(FAST_STORAGE_KEY, JSON.stringify(next));
+ } catch {
+ // Storage full or unavailable: the in-memory answer still serves this load.
+ }
+ for (const listener of fastListeners) listener();
+}
+
+const subscribeFast = (listener: () => void) => {
+ fastListeners.add(listener);
+ return () => fastListeners.delete(listener);
+};
+
+/** Whether `model` runs at its vendor's fast tier as far as this browser knows;
+ * when `wanted`, reads the backend's answer again once per page load. */
+export function useRememberedFastModel(backend: string, model: string | null | undefined, wanted: boolean): boolean {
+ const api = useApi();
+ const known = useSyncExternalStore(subscribeFast, () => (backend ? currentFast()[backend] ?? null : null));
+ useEffect(() => {
+ if (!wanted || !backend || fastReadThisLoad.has(backend)) return;
+ fastReadThisLoad.add(backend);
+ fetchBackendFastModels(api, backend).then(
+ (models) => rememberFastModels(backend, models),
+ () => undefined,
+ );
+ }, [api, backend, wanted]);
+ return Boolean(model && known?.includes(model));
+}
diff --git a/ui/src/lib/useNewSession.lifecycle.test.tsx b/ui/src/lib/useNewSession.lifecycle.test.tsx
index 3ae8040fd..235d8c8f2 100644
--- a/ui/src/lib/useNewSession.lifecycle.test.tsx
+++ b/ui/src/lib/useNewSession.lifecycle.test.tsx
@@ -4,6 +4,7 @@ import { afterEach, beforeEach, expect, it, vi } from 'vitest';
import type { ComposerAttachment } from '../components/workbench/Composer';
const mocks = vi.hoisted(() => ({
create: vi.fn(), upload: vi.fn(), fetch: vi.fn(), events: undefined as undefined | (() => void),
+ fastDefault: false, setFastDefault: vi.fn(),
projects: [
{ id: '中文项目', capabilities: { can_chat: true }, created_at: '2026-09-19T00:00:00Z' },
{ id: '其他项目', capabilities: { can_chat: true }, created_at: '2026-09-18T00:00:00Z' },
@@ -15,6 +16,8 @@ const api = {
mocks.events = onAuthorizationChanged;
return () => {};
},
+ getWorkbenchPrefs: async () => ({ background_work_banner_enabled: true, fast_mode_default: mocks.fastDefault }),
+ setFastModeDefault: mocks.setFastDefault,
};
vi.mock('../context/ApiContext', () => ({ useApi: () => api }));
vi.mock('../context/WorkbenchProjectsContext', () => ({ useWorkbenchProjectsTree: () => ({ projects: mocks.projects, projectsError: null, createSessionForProject: mocks.create }) }));
@@ -28,6 +31,8 @@ beforeEach(() => {
mocks.create.mockReset().mockImplementation(async () => ({ id: `session-${mocks.create.mock.calls.length}` }));
mocks.upload.mockReset().mockResolvedValue({ token: 'token', name: '中文.txt', mime: 'text/plain', size: 6, kind: 'file', url: '/api/media/token' });
mocks.fetch.mockReset().mockResolvedValue(new Response('{}', { status: 201 }));
+ mocks.fastDefault = false;
+ mocks.setFastDefault.mockReset().mockResolvedValue({});
});
afterEach(cleanup);
it('creates and submits once from a same-tick double send, only after explicit input', async () => {
@@ -196,3 +201,18 @@ it.each(['success', 'uncertain'])('already admitted POST %s survives suspension
expect(mocks.create).toHaveBeenCalledTimes(1);
expect(mocks.fetch).toHaveBeenCalledTimes(1);
});
+
+it('starts at the remembered fast default, creates with it, and makes a change the next default', async () => {
+ mocks.fastDefault = true;
+ const { result } = mount();
+ await waitFor(() => expect(result.current.speed).toBe('fast'));
+ await waitFor(() => expect(result.current.loaded).toBe(true));
+ await act(async () => { await result.current.send('快一点'); });
+ expect(mocks.create).toHaveBeenLastCalledWith('中文项目', { speed: 'fast' });
+ expect(mocks.setFastDefault).not.toHaveBeenCalled();
+
+ act(() => result.current.setSpeed(null));
+ expect(mocks.setFastDefault).toHaveBeenLastCalledWith(false);
+ await act(async () => { await result.current.send('标准速度'); });
+ expect(mocks.create).toHaveBeenLastCalledWith('中文项目', {});
+});
diff --git a/ui/src/lib/useNewSession.ts b/ui/src/lib/useNewSession.ts
index 9400d8e8d..edd974088 100644
--- a/ui/src/lib/useNewSession.ts
+++ b/ui/src/lib/useNewSession.ts
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useApi } from '../context/ApiContext';
import { useWorkbenchProjectsTree } from '../context/WorkbenchProjectsContext';
-import type { ApiContextType, VibeAgentBrief, WorkbenchProject, WorkbenchSessionCreate } from '../context/ApiContext';
+import type { ApiContextType, SessionSpeed, VibeAgentBrief, WorkbenchProject, WorkbenchSessionCreate } from '../context/ApiContext';
import { sortProjectsByRecent } from './projectOrder';
import { apiFetch } from './apiFetch';
import { uploadWorkbenchAttachment, workbenchUploadErrorTranslationKey, WorkbenchUploadError, type WorkbenchUploadResult } from './workbenchUpload';
@@ -51,6 +51,10 @@ export interface NewSessionState {
effectiveDefaultAgentName: string | null;
agentRoute: AgentRouteSelection;
setAgentRoute: (patch: AgentRouteSelection) => void;
+ /** Whether the new Session runs fast: starts at the remembered default, and a
+ * change here becomes that default. */
+ speed: SessionSpeed;
+ setSpeed: (speed: SessionSpeed) => void;
/** Creates the selected session, uploads staged files, submits once, then
* returns the navigation target. Failures leave the caller's draft intact. */
send: (text: string, attachments?: ComposerAttachment[]) => Promise<{ sessionId: string } | null>;
@@ -165,6 +169,33 @@ export function useNewSession({ active = true, loadErrorText, createFailedText,
const [agents, setAgents] = useState<VibeAgentBrief[]>([]);
const [defaultAgentName, setDefaultAgentName] = useState<string | null>(null);
const [agentProjectionLoaded, setAgentProjectionLoaded] = useState(false);
+ // Fast mode starts where the last picker choice left it (docs/plans/fast-mode.md):
+ // read again as the surface becomes active, since a chat's picker may have moved it.
+ const [speed, setSpeedState] = useState<SessionSpeed>(null);
+ const speedPickedRef = useRef(false);
+ const speedActive = active && surfaceActive;
+ useEffect(() => {
+ if (!speedActive) return;
+ speedPickedRef.current = false;
+ let cancelled = false;
+ api.getWorkbenchPrefs().then(
+ (prefs) => {
+ if (!cancelled && !speedPickedRef.current) setSpeedState(prefs?.fast_mode_default ? 'fast' : null);
+ },
+ () => undefined,
+ );
+ return () => {
+ cancelled = true;
+ };
+ }, [api, speedActive]);
+ const setSpeed = useCallback(
+ (next: SessionSpeed) => {
+ speedPickedRef.current = true;
+ setSpeedState(next);
+ void api.setFastModeDefault(next === 'fast').catch(() => undefined);
+ },
+ [api],
+ );
// The user's explicit pick in the composer; {} = "no pick, follow the
// project/global default". Kept separate from the effective route (below) so
// the project default can be derived live instead of copied into state.
@@ -342,6 +373,7 @@ export function useNewSession({ active = true, loadErrorText, createFailedText,
}
if (routeForCreate.model) overrides.model = routeForCreate.model;
if (routeForCreate.reasoning_effort) overrides.reasoning_effort = routeForCreate.reasoning_effort;
+ if (speed === 'fast') overrides.speed = 'fast';
const selection = JSON.stringify([target.id, overrides]);
try {
let pending = pendingSessionRef.current;
@@ -421,7 +453,7 @@ export function useNewSession({ active = true, loadErrorText, createFailedText,
}
}
},
- [loaded, target, routeForCreate, agents, createSessionForProject, createFailedText, errorText],
+ [loaded, target, routeForCreate, speed, agents, createSessionForProject, createFailedText, errorText],
);
// The dialog already committed the row through the provider (fenced against a
@@ -449,6 +481,8 @@ export function useNewSession({ active = true, loadErrorText, createFailedText,
effectiveDefaultAgentName,
agentRoute,
setAgentRoute: applyAgentRoute,
+ speed,
+ setSpeed,
send,
upsertSelectProject,
};
diff --git a/vibe/api.py b/vibe/api.py
index dcd34c3d6..d73837c82 100644
--- a/vibe/api.py
+++ b/vibe/api.py
@@ -2060,27 +2060,28 @@ def set_dock_order(
def get_workbench_prefs() -> dict:
"""Global workbench toggles the UI reads (state_meta-backed)."""
- from core.workbench_prefs import get_background_work_banner_enabled
+ from core.workbench_prefs import get_background_work_banner_enabled, get_fast_mode_default
return {
"ok": True,
"background_work_banner_enabled": get_background_work_banner_enabled(),
+ "fast_mode_default": get_fast_mode_default(),
}
-def set_workbench_prefs(*, background_work_banner_enabled: Optional[bool] = None) -> dict:
+def set_workbench_prefs(
+ *,
+ background_work_banner_enabled: Optional[bool] = None,
+ fast_mode_default: Optional[bool] = None,
+) -> dict:
"""Persist provided workbench toggles; omitted fields are left untouched."""
- from core.workbench_prefs import (
- get_background_work_banner_enabled,
- set_background_work_banner_enabled,
- )
+ from core.workbench_prefs import set_background_work_banner_enabled, set_fast_mode_default
if background_work_banner_enabled is not None:
set_background_work_banner_enabled(bool(background_work_banner_enabled))
- return {
- "ok": True,
- "background_work_banner_enabled": get_background_work_banner_enabled(),
- }
+ if fast_mode_default is not None:
+ set_fast_mode_default(bool(fast_mode_default))
+ return get_workbench_prefs()
def _vibe_agent_payload(agent, *, brief: bool = False, remote_safe: bool = False) -> dict:
diff --git a/vibe/models_dev_catalog.py b/vibe/models_dev_catalog.py
index 336180522..335a2e53c 100644
--- a/vibe/models_dev_catalog.py
+++ b/vibe/models_dev_catalog.py
@@ -298,6 +298,17 @@ def load_models_dev_catalog_with_date() -> tuple[dict[str, Any], float | None, b
return {}, None, _refresh_in_background()
+def cached_models_dev_stamp() -> tuple[str, int, int] | None:
+ """The cached copy's path, modification time and size, or None without one: a reader's cheap check for a new copy."""
+
+ path = _cache_path()
+ try:
+ stat = path.stat()
+ except OSError:
+ return None
+ return str(path), stat.st_mtime_ns, stat.st_size
+
+
def cached_models_dev_catalog() -> dict[str, Any]:
"""The cached copy as it stands, stale or not, and never a fetch.
diff --git a/vibe/ui_server.py b/vibe/ui_server.py
index f41bfdc33..01f49fc2b 100644
--- a/vibe/ui_server.py
+++ b/vibe/ui_server.py
@@ -6848,9 +6848,17 @@ def workbench_prefs_put():
from vibe import api
payload = request.json or {}
- raw = payload.get("background_work_banner_enabled")
- enabled = bool(raw) if raw is not None else None
- return jsonify(api.set_workbench_prefs(background_work_banner_enabled=enabled))
+
+ def flag(name: str) -> bool | None:
+ raw = payload.get(name)
+ return bool(raw) if raw is not None else None
+
+ return jsonify(
+ api.set_workbench_prefs(
+ background_work_banner_enabled=flag("background_work_banner_enabled"),
+ fast_mode_default=flag("fast_mode_default"),
+ )
+ )
@app.route("/api/csrf-token", methods=["GET"])
@@ -9965,10 +9973,13 @@ def sessions_create():
reasoning_effort=payload.get("reasoning_effort"),
title=payload.get("title"),
metadata=metadata,
+ speed=payload.get("speed"),
authorization_context=getattr(g, "authorization_context", None),
)
except LookupError as err:
return jsonify({"error": str(err)}), 404
+ except ValueError as err:
+ return jsonify({"error": str(err)}), 400
except workbench_sessions_service.ProjectAccessDeniedError as err:
code = err.code
message = t("error.projectAccessDenied", _request_ui_language())
@@ -10722,6 +10733,7 @@ async def sessions_update(session_id: str):
"agent_variant",
"model",
"reasoning_effort",
+ "speed",
"visibility",
"pinned",
"scope_id",