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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
fix(model-hub): configure prompt cache TTL routes (#3003)
Call White5ac7e72bab18
diff --git a/config/v2_config.py b/config/v2_config.pyindex f49da2973..a3f1bf331 100644--- a/config/v2_config.py+++ b/config/v2_config.py@@ -2562,14 +2562,21 @@ class ModelHubRouteHopConfig:@dataclassclass ModelHubRouteConfig:hops: tuple[ModelHubRouteHopConfig, ...] = ()+ cache_ttl: Optional[Literal["5m", "30m", "1h", "12h"]] = None@classmethoddef from_payload(cls, payload: object, *, repairing: bool = False) -> "ModelHubRouteConfig":- if not isinstance(payload, dict) or set(payload) != {"hops"}:+ if not isinstance(payload, dict) or set(payload) - {"hops", "cache_ttl"} or "hops" not in payload:raise ValueError("Config 'model_hub.agents.routes' entries must contain hops")hops = payload.get("hops")if not isinstance(hops, list):raise ValueError("Config 'model_hub.agents.routes.hops' must be an array")+ cache_ttl = payload.get("cache_ttl")+ if cache_ttl is not None and (+ not isinstance(cache_ttl, str)+ or cache_ttl not in {"5m", "30m", "1h", "12h"}+ ):+ raise ValueError("Config 'model_hub.agents.routes.cache_ttl' is invalid")return cls(hops=tuple(_collapse_settled_duplicates(@@ -2579,11 +2586,15 @@ class ModelHubRouteConfig:"Config 'model_hub.agents.routes.hops' must contain unique pairs",repairing=repairing,)- )+ ),+ cache_ttl=cache_ttl,)def to_payload(self) -> dict:- return {"hops": [hop.to_payload() for hop in self.hops]}+ payload = {"hops": [hop.to_payload() for hop in self.hops]}+ if self.cache_ttl is not None:+ payload["cache_ttl"] = self.cache_ttl+ return payloaddef normalized_model_hub_override(route: ModelHubRouteConfig | None) -> ModelHubRouteConfig | None:diff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.pyindex 64b91ba8b..94c956c29 100644--- a/core/agent_core/agent/loop.py+++ b/core/agent_core/agent/loop.py@@ -209,8 +209,12 @@ def _mind_text(files: Mapping[str, Optional[str]]) -> Optional[str]:def _cache_of(origin: Origin) -> tuple[str, str]:- """The upstream prompt cache an origin's requests use: its provider and model (C-9 section 3). The protocol that- reaches the gateway, converted or not (a Google hop is called over Chat), does not change the cache."""+ """The upstream prompt cache an origin's requests use: provider and model.++ Canonical response rows and served-hop metadata carry the credential-free Source identity, but this C-9 cache+ clock intentionally keys by provider/model. Same-provider/model Sources therefore share one clock; Model Hub cache+ overrides are route-wide rather than a claim of per-Source clocks.+ """return origin.provider, origin.model@@ -389,8 +393,8 @@ class Agent:# The images the run's committed tool results generated, which its final delivers: a reply even without text# (``has_reply``). Read from the committed rows, so a result another writer settled counts as it committed.self._generated_images: list[HostedImage] = []- # When each upstream prompt cache was last used in this Agent: the end of its latest model call, by the provider- # and model that served it (``_cache_of``, C-9 section 3).+ # The C-9 cache clock deliberately keys the served provider/model boundary;+ # canonical rows also retain Source identity, but it is not a separate clock.self._last_model_at: dict[tuple[str, str], float] = {}self._seq = 0@@ -1517,7 +1521,9 @@ class Agent:Its use is the latest model call's end or response row's commit served by the route's upstream cache(``_cache_of``), so a long response counts as use until it ends, and a restarted Agent reads the rows. A route- with no use in the Session yet takes the latest use of any route: every error leans toward a warm cache.+ with no use in the Session yet takes the latest use of any route: every error leans toward a warm cache. The+ row also retains the served Source identity for canonical replay and scrubbing, but this C-9 clock intentionally+ keys by provider/model."""used = dict(self._last_model_at)for row in self._rows:diff --git a/core/agent_core/ai/openai_responses.py b/core/agent_core/ai/openai_responses.pyindex 56b7e39a9..cfeaac1ac 100644--- a/core/agent_core/ai/openai_responses.py+++ b/core/agent_core/ai/openai_responses.py@@ -1335,6 +1335,8 @@ def build_responses_payload("stream": True,"store": False,}+ if request.endpoint.cache_ttl_wire and request.endpoint.cache_ttl in {"30m", "12h"}:+ payload["prompt_cache_options"] = {"ttl": request.endpoint.cache_ttl}# A hosted tool this hop runs natively is sent as the provider's declaration in its spec's place (§4.1).native = native_hosted_tools(request)tools = [diff --git a/core/agent_core/ai/provider.py b/core/agent_core/ai/provider.pyindex edc0559c9..5d13834dd 100644--- a/core/agent_core/ai/provider.py+++ b/core/agent_core/ai/provider.py@@ -105,6 +105,13 @@ class ModelEndpoint:token: str = field(repr=False)request_headers: Mapping[str, str] = field(default_factory=dict)provider: str = ""+ #: Route-local cache lifetime override. The Model Hub validates provider+ #: semantics before it reaches the adapter; unknown/relay routes use it only+ #: for C-9 clearing, while official OpenAI Responses routes may also wire it.+ cache_ttl: Optional[Literal["5m", "30m", "1h", "12h"]] = None+ #: True only when Model Hub confirmed that the provider-specific TTL can be+ #: sent on the wire (currently official OpenAI Responses GPT-5.6+).+ cache_ttl_wire: bool = False#: The hop's Source (``HopResolution.source_id``): the pin of a request that carries native hosted content.source_id: Optional[str] = None#: That Source's credential-free identity (``HopResolution.source_identity``): the account a response's opaquediff --git a/core/agent_core/harness/context.py b/core/agent_core/harness/context.pyindex aed434fcb..525b54686 100644--- a/core/agent_core/harness/context.py+++ b/core/agent_core/harness/context.py@@ -90,8 +90,12 @@ CLEARABLE_TOOLS = frozenset({"read"}) | COMMAND_TOOLS#: How long a route's provider prompt cache stays warm after its last use, in seconds, by cache family (section 3):#: the documented lifetime of the cache mode Vibey requests for the conversation, where clearable results live.#: ``anthropic``: the message breakpoints' ``cache_control`` is ephemeral with no ``ttl``, 5 minutes, refreshed on use.-#: ``openai-gpt-5.6``: OpenAI models from GPT-5.6 keep a prefix 30 minutes after its last write or reuse, the default-#: and only ``prompt_cache_options.ttl``; Vibey sends none.+#: ``openai-gpt-5.6``: OpenAI Responses GPT-5.6+ defaults to a 30-minute prefix cache; a validated official route may opt into ``12h`` via ``prompt_cache_options.ttl``. The latter has a 2.5x cache-write rate versus 1.25x for 30m, while reads use the same cached-input rate.+#: Route overrides are intentionally closed: they are persisted as operator-visible+#: duration labels, not arbitrary provider claims. ``12h`` is admitted only for+#: official OpenAI Responses GPT-5.6+ routes by Model Hub validation.+CACHE_TTL_OVERRIDES: Mapping[str, float] = {"5m": 300.0, "30m": 1_800.0, "1h": 3_600.0, "12h": 43_200.0}+#: Earlier supported OpenAI models may expose the separate Chat Completions ``prompt_cache_retention`` modes ``in_memory`` or ``24h`` depending on model and organization policy; Avibe does not infer or send that policy-dependent option, so those routes stay on the conservative built-in estimate unless explicitly supported later.CACHE_TTLS: Mapping[str, float] = {"anthropic": 300.0, "openai-gpt-5.6": 1_800.0}#: Any other route, or one not identified unambiguously: clearing a warm cache costs a full-price re-read of the#: context, while leaving a cold one only keeps some old output, so an unknown lifetime counts as an hour.@@ -652,8 +656,14 @@ _GPT_MODEL = re.compile(r"gpt-(\d+)(?:\.(\d+))?(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?def cache_ttl_s(endpoint: ModelEndpoint) -> float:- """How long the provider cache of a request's route stays warm (section 3): its family's documented lifetime in- ``CACHE_TTLS``, else ``CACHE_TTL_UNKNOWN_S``."""+ """How long the provider cache of a request's route stays warm (section 3).++ A validated Model Hub route override wins. Otherwise use the documented+ family lifetime, with OpenAI GPT-5.6+ recognized only on Responses; unknown+ routes keep the conservative one-hour estimate.+ """+ if endpoint.cache_ttl is not None:+ return CACHE_TTL_OVERRIDES.get(endpoint.cache_ttl, CACHE_TTL_UNKNOWN_S)family = _cache_family(endpoint)return CACHE_TTL_UNKNOWN_S if family is None else CACHE_TTLS[family]@@ -662,7 +672,11 @@ def _cache_family(endpoint: ModelEndpoint) -> Optional[str]:"""The route's cache family from its provider, protocol, and whole model id; None unless unambiguous."""if endpoint.provider == "anthropic" and endpoint.protocol == "anthropic":return "anthropic"- gpt = _GPT_MODEL.fullmatch(endpoint.model_id) if endpoint.provider == "openai" else None+ gpt = (+ _GPT_MODEL.fullmatch(endpoint.model_id)+ if endpoint.provider == "openai" and endpoint.protocol == "openai_responses"+ else None+ )if gpt is not None and (int(gpt[1]), int(gpt[2] or 0)) >= (5, 6):return "openai-gpt-5.6"return Nonediff --git a/core/handlers/model_hub/pricing.py b/core/handlers/model_hub/pricing.pyindex 5b075341c..207f7533c 100644--- a/core/handlers/model_hub/pricing.py+++ b/core/handlers/model_hub/pricing.py@@ -115,6 +115,8 @@ class ModelPrice:cache_read: floatcache_write: floatcache_write_1h: float+ cache_write_30m: float = 0.0+ cache_write_12h: float = 0.0# Whether the table lists a cache write above input. The one-hour figure# counts only when listed: its default is a multiple of input for every# model, so a defaulted one says nothing about the vendor.@@ -227,6 +229,8 @@ def _flat_price(cost: object) -> Optional[ModelPrice]:cache_read = _price(cost.get("cache_read"))cache_write = _price(cost.get("cache_write"))cache_write_1h = _price(cost.get("cache_write_1h"))+ cache_write_30m = _price(cost.get("cache_write_30m"))+ cache_write_12h = _price(cost.get("cache_write_12h"))return ModelPrice(input=input_price,output=output_price,@@ -235,7 +239,11 @@ def _flat_price(cost: object) -> Optional[ModelPrice]:cache_write_1h=(input_price * _CACHE_WRITE_1H_INPUT_MULTIPLE if cache_write_1h is None else cache_write_1h),- charges_cache_writes=any(price is not None and price > input_price for price in (cache_write, cache_write_1h)),+ cache_write_30m=input_price * 1.25 if cache_write_30m is None else cache_write_30m,+ cache_write_12h=input_price * 2.5 if cache_write_12h is None else cache_write_12h,+ charges_cache_writes=any(+ price is not None and price > input_price for price in (cache_write, cache_write_1h)+ ),)@@ -462,18 +470,25 @@ def row_cost(row: Mapping[str, Any], price: Optional[ModelPrice]) -> Cost:cache_read = min(int(row.get("cached_input_tokens") or 0), input_tokens)cache_write = min(int(row.get("cache_write_input_tokens") or 0), input_tokens - cache_read)cache_write_1h = min(int(row.get("cache_write_1h_input_tokens") or 0), cache_write)+ remaining = max(0, cache_write - cache_write_1h)+ cache_write_30m = min(int(row.get("cache_write_30m_input_tokens") or 0), remaining)+ cache_write_12h = min(int(row.get("cache_write_12h_input_tokens") or 0), remaining - cache_write_30m)+ unknown_write = max(0, remaining - cache_write_30m - cache_write_12h)fresh = input_tokens - cache_read - cache_writeusd = (fresh * price.input+ cache_read * price.cache_read- + (cache_write - cache_write_1h) * price.cache_write+ + unknown_write * price.cache_write+ + cache_write_30m * price.cache_write_30m+ + cache_write_12h * price.cache_write_12h+ cache_write_1h * price.cache_write_1h+ output_tokens * price.output) / 1_000_000uncaptured = int(row.get("cache_write_uncaptured_reports") or 0) > 0+ ttl_uncaptured = int(row.get("cache_write_ttl_uncaptured_reports") or 0) > 0return Cost(api_cost_usd=usd,- api_cost_lower_bound=unreported or (uncaptured and price.charges_cache_writes),+ api_cost_lower_bound=unreported or ttl_uncaptured or (uncaptured and price.charges_cache_writes),)@@ -728,12 +743,19 @@ def hosted_response_cost(return ("reported", reported_usd)if model_price is None or usage is None:return None+ if usage.cache_write_ttl_uncaptured_reports:+ # HostedCost has no lower-bound bit. Do not publish a list amount when+ # cache-write lifetime evidence is incomplete; the usage ledger carries+ # the lower-bound witness for aggregate valuation instead.+ return Nonerow = {"input_tokens": usage.input_tokens,"output_tokens": usage.output_tokens,"cached_input_tokens": usage.cached_input_tokens,"cache_write_input_tokens": usage.cache_write_input_tokens,"cache_write_1h_input_tokens": usage.cache_write_1h_input_tokens,+ "cache_write_30m_input_tokens": usage.cache_write_30m_input_tokens,+ "cache_write_12h_input_tokens": usage.cache_write_12h_input_tokens,"requests": 1,"token_reports": 1,"context_tier": context_tier_size(model_price, usage.input_tokens),diff --git a/core/handlers/model_hub/resolver.py b/core/handlers/model_hub/resolver.pyindex 816fae44a..3f5db1f34 100644--- a/core/handlers/model_hub/resolver.py+++ b/core/handlers/model_hub/resolver.py@@ -23,6 +23,12 @@ BackendName = AgentBackendResolutionChannel = Literal["direct", "native_cli", "hub", "unavailable"]SupplyStatus = Literal["ok", "degraded", "waiting", "interrupted"]RouteOrigin = Literal["automatic", "manual", "passthrough"]+CacheTtl = Literal["5m", "30m", "1h", "12h"]+_CACHE_TTL_VALUES = frozenset(("5m", "30m", "1h", "12h"))+_GPT_MODEL = re.compile(+ r"gpt-(?P<major>\d+)(?:\.(?P<minor>\d+))?(?:-[a-z0-9]+(?:[.-][a-z0-9]+)*)?",+ re.ASCII,+)@dataclass(frozen=True)@@ -30,6 +36,7 @@ class EffectiveModelRoute:manual_override: ModelHubRouteConfig | Noneroute_origin: RouteOrigin | Nonehops: tuple[ModelHubRouteHopConfig, ...]+ cache_ttl: CacheTtl | None = None@dataclass(frozen=True)@@ -86,6 +93,8 @@ class ModelHubTurnResolution:source: ModelHubSourceConfig | Nonemanual_override: ModelHubRouteConfig | None = Noneroute_origin: RouteOrigin | None = None+ cache_ttl: CacheTtl | None = None+ cache_ttl_wire: bool = Falsematching_sources: tuple[ModelHubSourceConfig, ...] = ()candidates: tuple[ModelHubSourceConfig, ...] = ()candidate_hops: tuple[ExactHopInspection, ...] = ()@@ -274,6 +283,69 @@ def source_supports_passthrough(source: ModelHubSourceConfig) -> bool:return source.kind == "api_key" and source.supply_channel == "hub" and source.protocol != "search"+def is_official_openai_responses_route(+ config: ModelHubConfig,+ backend: BackendName,+ route: ModelHubRouteConfig,+) -> bool:+ """Whether every hop is the official OpenAI Responses GPT-5.6+ route.++ A missing/custom endpoint is deliberately not treated as official: an+ OpenAI-compatible relay may speak the same wire protocol without honoring+ OpenAI's prompt-cache retention option.+ """++ if backend != "vibey" or not route.hops:+ return False+ sources = {source.id: source for source in config.sources}+ for hop in route.hops:+ source = sources.get(hop.source_id)+ match = _GPT_MODEL.fullmatch(hop.model_id)+ if (+ source is None+ or source.vendor != "openai"+ or source.protocol != "openai_responses"+ or source.base_url is not None+ or match is None+ or (int(match.group("major")), int(match.group("minor") or 0)) < (5, 6)+ ):+ return False+ return True+++def validate_cache_ttl_override(+ config: ModelHubConfig,+ backend: BackendName,+ route: ModelHubRouteConfig,+) -> None:+ """Validate route-local cache lifetime without granting relay OpenAI semantics."""++ ttl = route.cache_ttl+ if ttl is None:+ return+ if backend != "vibey":+ raise ValueError("cache_ttl is supported only for Vibey routes")+ if not isinstance(ttl, str) or ttl not in _CACHE_TTL_VALUES or not route.hops:+ raise ValueError("cache_ttl is not supported for this route")+ official_openai = is_official_openai_responses_route(config, backend, route)+ if ttl == "12h" and not official_openai:+ raise ValueError("12h is supported only by an official OpenAI Responses GPT-5.6+ route")+ if official_openai and ttl not in {"30m", "12h"}:+ raise ValueError("official OpenAI Responses routes support only 30m or 12h")+ if (+ backend == "vibey"+ and all(+ (source := next((item for item in config.sources if item.id == hop.source_id), None)) is not None+ and source.vendor == "anthropic"+ and source.protocol == "anthropic"+ and source.base_url is None+ for hop in route.hops+ )+ and ttl != "5m"+ ):+ raise ValueError("official Anthropic conversation breakpoints support only 5m")++def effective_model_route(config: ModelHubConfig,backend: BackendName,@@ -284,7 +356,7 @@ def effective_model_route(agent = config.agents[backend]override = normalized_model_hub_override(agent.routes.get(requested_model))if override is not None:- return EffectiveModelRoute(override, "manual", override.hops)+ return EffectiveModelRoute(override, "manual", override.hops, override.cache_ttl)if not requested_model or not any(model.id == requested_model for model in agent.models):return EffectiveModelRoute(None, None, ())by_id = {source.id: source for source in config.sources}@@ -578,6 +650,12 @@ def resolve_model_hub_turn(first = first_inspection.source if first_inspection is not None else Noneif first is not None:channel = first.supply_channel+ cache_ttl = route.cache_ttl+ if route.manual_override is not None:+ try:+ validate_cache_ttl_override(config, backend, route.manual_override)+ except ValueError:+ cache_ttl = Nonereturn ModelHubTurnResolution(backend=backend,channel=channel,@@ -586,6 +664,11 @@ def resolve_model_hub_turn(source=first,manual_override=route.manual_override,route_origin=route.route_origin,+ cache_ttl=cache_ttl,+ cache_ttl_wire=(+ cache_ttl in {"30m", "12h"}+ and is_official_openai_responses_route(config, backend, route)+ ),matching_sources=matching_sources,candidates=candidates,candidate_hops=runnable_inspections,diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.pyindex 2b5f61cae..a776d8ef0 100644--- a/core/handlers/model_hub/service.py+++ b/core/handlers/model_hub/service.py@@ -251,6 +251,7 @@ from .resolver import (source_model_retired,source_supports_passthrough,source_runnable,+ validate_cache_ttl_override,)from .revocations import CredentialRevocationJournal, PendingCredentialRevocation, RevocationOperationfrom .retry import (@@ -5948,16 +5949,25 @@ class ModelHubService:or normalized_model_id(model_id) != model_idor not isinstance(payload, dict)or set(payload)- - {"hops", "force", "would_remove_hops", "would_interrupt"}+ - {"hops", "cache_ttl", "force", "would_remove_hops", "would_interrupt"}or "hops" not in payloador ("force" in payload and not isinstance(payload["force"], bool))):raise ModelHubError("mapping_target_unavailable", status=409)try:- route = ModelHubRouteConfig.from_payload({"hops": payload["hops"]})+ route = ModelHubRouteConfig.from_payload({+ "hops": payload["hops"],+ "cache_ttl": payload.get("cache_ttl"),+ })if any(normalized_model_id(hop["model_id"]) != hop["model_id"] for hop in payload["hops"]):raise ValueError("noncanonical model")- except (TypeError, ValueError):+ except (TypeError, ValueError) as error:+ if payload.get("cache_ttl") is not None:+ raise ModelHubError(+ "cache_ttl_unsupported",+ status=422,+ data={"reason": str(error)},+ ) from Noneraise ModelHubError("mapping_target_unavailable", status=409) from Nonereturn await self._write_agent_chain(backend, model_id, route, payload)@@ -5975,6 +5985,15 @@ class ModelHubService:model_id not in self._agent_menu_model_ids(agent)):raise ModelHubError("mapping_target_unavailable", status=409)+ if route is not None:+ try:+ validate_cache_ttl_override(config, cast(BackendName, backend), route)+ except ValueError as error:+ raise ModelHubError(+ "cache_ttl_unsupported",+ status=422,+ data={"reason": str(error)},+ ) from Noneby_id = {source.id: source for source in config.sources}old_pairs = {(hop.source_id, hop.model_id)@@ -6009,7 +6028,13 @@ class ModelHubService:route = ModelHubRouteConfig.from_payload(raw) if raw is not None else Noneif raw is not None and any(normalized_model_id(hop["model_id"]) != hop["model_id"] for hop in raw["hops"]):raise ValueError("noncanonical model")- except (TypeError, ValueError):+ except (TypeError, ValueError) as error:+ if isinstance(raw, dict) and raw.get("cache_ttl") is not None:+ raise ModelHubError(+ "cache_ttl_unsupported",+ status=422,+ data={"reason": str(error)},+ ) from Noneraise ModelHubError("mapping_target_unavailable", status=409) from Noneconfig = self._clone_config(self.store.load())agent = self._validate_route_override(config, backend, model_id, route)diff --git a/core/handlers/model_hub/stream_wire.py b/core/handlers/model_hub/stream_wire.pyindex e9faca980..7d9b12907 100644--- a/core/handlers/model_hub/stream_wire.py+++ b/core/handlers/model_hub/stream_wire.py@@ -408,9 +408,16 @@ class ProtocolUsageReport:cached_input_tokens: int = 0output_tokens: int = 0# Input written to the prompt cache: a subset of input disjoint from cached- # input, and the part of it written with the one-hour lifetime.+ # input. The lifetime-specific fields are disjoint subsets of this total;+ # Anthropic uses the one-hour field and official OpenAI Responses uses the+ # separate 30-minute and 12-hour fields.cache_write_input_tokens: int = 0cache_write_1h_input_tokens: int = 0+ cache_write_30m_input_tokens: int = 0+ cache_write_12h_input_tokens: int = 0+ # Count of reports whose cache-write lifetime evidence was absent or+ # invalid. This is per protocol report and is summed when calls fold.+ cache_write_ttl_uncaptured_reports: int = 0@classmethoddef of(@@ -421,6 +428,9 @@ class ProtocolUsageReport:output_tokens: int,cache_write_input_tokens: int = 0,cache_write_1h_input_tokens: int = 0,+ cache_write_30m_input_tokens: int = 0,+ cache_write_12h_input_tokens: int = 0,+ cache_write_ttl_uncaptured_reports: int = 0,) -> "ProtocolUsageReport":"""Build one report with the cached-input subset invariant enforced.@@ -433,14 +443,44 @@ class ProtocolUsageReport:the input left after cache reads, and one-hour writes are part of them."""+ raw_values = (+ input_tokens,+ cached_input_tokens,+ cache_write_input_tokens,+ cache_write_1h_input_tokens,+ cache_write_30m_input_tokens,+ cache_write_12h_input_tokens,+ )+ invalid_ttl = any(value < 0 for value in raw_values[2:]) or (+ cache_write_input_tokens > max(0, input_tokens - max(0, cached_input_tokens))+ ) or (+ cache_write_1h_input_tokens + cache_write_30m_input_tokens + cache_write_12h_input_tokens+ > cache_write_input_tokens+ )+ input_tokens = max(0, input_tokens)+ cached_input_tokens = max(0, cached_input_tokens)+ output_tokens = max(0, output_tokens)+ cache_write_input_tokens = max(0, cache_write_input_tokens)+ cache_write_1h_input_tokens = max(0, cache_write_1h_input_tokens)+ cache_write_30m_input_tokens = max(0, cache_write_30m_input_tokens)+ cache_write_12h_input_tokens = max(0, cache_write_12h_input_tokens)cached = min(cached_input_tokens, input_tokens)cache_write = min(cache_write_input_tokens, input_tokens - cached)+ cache_write_1h = min(cache_write_1h_input_tokens, cache_write)+ cache_write_30m = min(cache_write_30m_input_tokens, max(0, cache_write - cache_write_1h))+ cache_write_12h = min(+ cache_write_12h_input_tokens, max(0, cache_write - cache_write_1h - cache_write_30m)+ )+ ttl_uncaptured = max(max(0, cache_write_ttl_uncaptured_reports), int(invalid_ttl))return cls(input_tokens=input_tokens,cached_input_tokens=cached,output_tokens=output_tokens,cache_write_input_tokens=cache_write,- cache_write_1h_input_tokens=min(cache_write_1h_input_tokens, cache_write),+ cache_write_1h_input_tokens=cache_write_1h,+ cache_write_30m_input_tokens=cache_write_30m,+ cache_write_12h_input_tokens=cache_write_12h,+ cache_write_ttl_uncaptured_reports=ttl_uncaptured,)def merge(self, other: "ProtocolUsageReport") -> "ProtocolUsageReport":@@ -459,6 +499,16 @@ class ProtocolUsageReport:cache_write_1h_input_tokens=max(self.cache_write_1h_input_tokens, other.cache_write_1h_input_tokens),+ cache_write_30m_input_tokens=max(+ self.cache_write_30m_input_tokens, other.cache_write_30m_input_tokens+ ),+ cache_write_12h_input_tokens=max(+ self.cache_write_12h_input_tokens, other.cache_write_12h_input_tokens+ ),+ cache_write_ttl_uncaptured_reports=max(+ self.cache_write_ttl_uncaptured_reports,+ other.cache_write_ttl_uncaptured_reports,+ ),)@@ -534,6 +584,11 @@ class ProtocolUsageTaxonomy:# Protocols that report no cache writes leave these empty.cache_write_paths: tuple[tuple[str, ...], ...] = ()cache_write_1h_paths: tuple[tuple[str, ...], ...] = ()+ # Lifetime-specific OpenAI Responses write breakdowns. When these are+ # declared, both must be present and sum to cache_write_tokens; otherwise+ # the known total remains usable but is marked incomplete for pricing.+ cache_write_30m_paths: tuple[tuple[str, ...], ...] = ()+ cache_write_12h_paths: tuple[tuple[str, ...], ...] = ()@dataclass(frozen=True)@@ -767,6 +822,9 @@ PROTOCOL_STREAM_TAXONOMY: Final[Mapping[str, ProtocolStreamTaxonomy]] = {input_paths=(("input_tokens",),),cached_input_paths=(("input_tokens_details", "cached_tokens"),),output_paths=(("output_tokens",),),+ cache_write_paths=(("input_tokens_details", "cache_write_tokens"),),+ cache_write_30m_paths=(("input_tokens_details", "cache_write_tokens_details", "ttl_30m_tokens"),),+ cache_write_12h_paths=(("input_tokens_details", "cache_write_tokens_details", "ttl_12h_tokens"),),),),"openai_chat": ProtocolStreamTaxonomy(@@ -949,12 +1007,38 @@ def extract_protocol_usage(output_tokens = _usage_sum(container, taxonomy.output_paths)if input_tokens is None and cached_input_tokens is None and output_tokens is None:continue+ reported_cache_write_total = _usage_sum(container, taxonomy.cache_write_paths)+ cache_write_30m = _usage_sum(container, taxonomy.cache_write_30m_paths)+ cache_write_12h = _usage_sum(container, taxonomy.cache_write_12h_paths)+ cache_write_total = reported_cache_write_total+ ttl_uncaptured = 0+ if taxonomy.cache_write_30m_paths or taxonomy.cache_write_12h_paths:+ has_cache_write_evidence = (+ reported_cache_write_total is not None+ or cache_write_30m is not None+ or cache_write_12h is not None+ )+ if has_cache_write_evidence and cache_write_total is None and cache_write_30m is not None and cache_write_12h is not None:+ # The documented OpenAI breakdowns are disjoint and sum to+ # cache_write_tokens; retain that evidence, but keep the+ # missing total visible as an incomplete report.+ cache_write_total = cache_write_30m + cache_write_12h+ if has_cache_write_evidence and (+ reported_cache_write_total is None+ or cache_write_30m is None+ or cache_write_12h is None+ or cache_write_30m + cache_write_12h != cache_write_total+ ):+ ttl_uncaptured = 1candidate = ProtocolUsageReport.of(input_tokens=input_tokens or 0,cached_input_tokens=cached_input_tokens or 0,output_tokens=output_tokens or 0,- cache_write_input_tokens=_usage_sum(container, taxonomy.cache_write_paths) or 0,+ cache_write_input_tokens=cache_write_total or 0,cache_write_1h_input_tokens=_usage_sum(container, taxonomy.cache_write_1h_paths) or 0,+ cache_write_30m_input_tokens=cache_write_30m or 0,+ cache_write_12h_input_tokens=cache_write_12h or 0,+ cache_write_ttl_uncaptured_reports=ttl_uncaptured,)report = candidate if report is None else report.merge(candidate)return report@@ -977,12 +1061,35 @@ def _usage_from_scalar_paths(output_tokens = usage_sum(taxonomy.output_paths)if input_tokens is None and cached_input_tokens is None and output_tokens is None:continue+ reported_cache_write_total = usage_sum(taxonomy.cache_write_paths)+ cache_write_30m = usage_sum(taxonomy.cache_write_30m_paths)+ cache_write_12h = usage_sum(taxonomy.cache_write_12h_paths)+ cache_write_total = reported_cache_write_total+ ttl_uncaptured = 0+ if taxonomy.cache_write_30m_paths or taxonomy.cache_write_12h_paths:+ has_cache_write_evidence = (+ reported_cache_write_total is not None+ or cache_write_30m is not None+ or cache_write_12h is not None+ )+ if has_cache_write_evidence and cache_write_total is None and cache_write_30m is not None and cache_write_12h is not None:+ cache_write_total = cache_write_30m + cache_write_12h+ if has_cache_write_evidence and (+ reported_cache_write_total is None+ or cache_write_30m is None+ or cache_write_12h is None+ or cache_write_30m + cache_write_12h != cache_write_total+ ):+ ttl_uncaptured = 1candidate = ProtocolUsageReport.of(input_tokens=input_tokens or 0,cached_input_tokens=cached_input_tokens or 0,output_tokens=output_tokens or 0,- cache_write_input_tokens=usage_sum(taxonomy.cache_write_paths) or 0,+ cache_write_input_tokens=cache_write_total or 0,cache_write_1h_input_tokens=usage_sum(taxonomy.cache_write_1h_paths) or 0,+ cache_write_30m_input_tokens=cache_write_30m or 0,+ cache_write_12h_input_tokens=cache_write_12h or 0,+ cache_write_ttl_uncaptured_reports=ttl_uncaptured,)report = candidate if report is None else report.merge(candidate)return report@@ -1043,6 +1150,8 @@ def _protocol_projection_paths(protocol: str) -> frozenset[JSONPath]:taxonomy.usage.output_paths,taxonomy.usage.cache_write_paths,taxonomy.usage.cache_write_1h_paths,+ taxonomy.usage.cache_write_30m_paths,+ taxonomy.usage.cache_write_12h_paths,):paths.update((*container_path, *leaf_path) for leaf_path in leaf_paths)return frozenset(paths)diff --git a/core/handlers/model_hub/usage.py b/core/handlers/model_hub/usage.pyindex b3a94fa33..125d52517 100644--- a/core/handlers/model_hub/usage.py+++ b/core/handlers/model_hub/usage.py@@ -124,16 +124,19 @@ _COUNTER_KEYS: Final = ("output_tokens","cache_write_input_tokens","cache_write_1h_input_tokens",+ "cache_write_30m_input_tokens",+ "cache_write_12h_input_tokens","cache_write_uncaptured_reports",+ "cache_write_ttl_uncaptured_reports",)# Counters added after files were already written. A released row lacks them, and# what it lacks is knowledge, not usage: its cache writes are inside its input but# were never split out, so every token report it carries counts as uncaptured.# Additive only — no stored row is rewritten to acquire them.-_CACHE_WRITE_KEYS: Final = (- "cache_write_input_tokens",- "cache_write_1h_input_tokens",- "cache_write_uncaptured_reports",+_NEW_CACHE_WRITE_KEYS: Final = (+ "cache_write_30m_input_tokens",+ "cache_write_12h_input_tokens",+ "cache_write_ttl_uncaptured_reports",)# The cross-field guarantees the read contract makes, as (subset, superset).# Each one is repaired on read, so a corrupt or hand-edited file degrades into a@@ -144,7 +147,10 @@ _COUNTER_SUBSETS: Final = (("cached_input_tokens", "input_tokens"),("token_reports", "requests"),("cache_write_uncaptured_reports", "token_reports"),+ ("cache_write_ttl_uncaptured_reports", "token_reports"),("cache_write_1h_input_tokens", "cache_write_input_tokens"),+ ("cache_write_30m_input_tokens", "cache_write_input_tokens"),+ ("cache_write_12h_input_tokens", "cache_write_input_tokens"),)@@ -156,7 +162,10 @@ def _released_cache_write_counters(value: dict) -> dict[str, int]:return {"cache_write_input_tokens": 0,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": max(0, uncaptured),+ "cache_write_ttl_uncaptured_reports": 0,}@@ -170,6 +179,12 @@ def _repair_cache_writes(counters: dict) -> None:counters["cache_write_1h_input_tokens"] = min(counters["cache_write_1h_input_tokens"], counters["cache_write_input_tokens"])+ remaining = max(0, counters["cache_write_input_tokens"] - counters["cache_write_1h_input_tokens"])+ counters["cache_write_30m_input_tokens"] = min(counters["cache_write_30m_input_tokens"], remaining)+ counters["cache_write_12h_input_tokens"] = min(+ counters["cache_write_12h_input_tokens"],+ max(0, remaining - counters["cache_write_30m_input_tokens"]),+ )# A service row's counts (`web-search-services.md` §4.3): requests sent, those the@@ -729,7 +744,7 @@ def _normalize_hourly_totals(value: object, *, service: bool = False) -> Optionareturn _normalize_service_totals(value)if not isinstance(value, dict):return None- if all(key not in value for key in _CACHE_WRITE_KEYS):+ if any(key not in value for key in _NEW_CACHE_WRITE_KEYS):value = {**_released_cache_write_counters(value), **value}totals: dict[str, int] = {}for key in _COUNTER_KEYS:@@ -782,7 +797,8 @@ def _normalize_row(row: object) -> Optional[dict]:context_tier = row.get("context_tier", 0)if not isinstance(context_tier, int) or isinstance(context_tier, bool) or context_tier < 0:return None- if all(key not in row for key in _CACHE_WRITE_KEYS):+ legacy_cache_write_shape = any(key not in row for key in _NEW_CACHE_WRITE_KEYS)+ if legacy_cache_write_shape:row = {**_released_cache_write_counters(row), **row}counters: dict[str, int] = {}for key in _COUNTER_KEYS:@@ -798,6 +814,8 @@ def _normalize_row(row: object) -> Optional[dict]:**({"context_tier": context_tier} if context_tier else {}),**counters,}+ if legacy_cache_write_shape:+ normalized["_legacy_cache_write_shape"] = Trueif row.get("history_degraded") is True:# Internal witness that an earlier read lost evidence. It never crosses# the public usage-summary boundary.@@ -1150,11 +1168,32 @@ def _recency(return (row["day"], metered)+def _persistable_row(row: dict) -> dict:+ """Keep released cache-write rows byte-compatible until a new write touches them."""++ if not row.get("_legacy_cache_write_shape"):+ return row++ def strip(value: object) -> object:+ if isinstance(value, list):+ return [strip(item) for item in value]+ if not isinstance(value, dict):+ return value+ return {+ key: strip(item)+ for key, item in value.items()+ if key not in _NEW_CACHE_WRITE_KEYS and key != "_legacy_cache_write_shape"+ }++ return strip(row)def _cache_write_increment(usage: Optional[ProtocolUsageReport]) -> dict[str, int]:return {"cache_write_input_tokens": usage.cache_write_input_tokens if usage else 0,"cache_write_1h_input_tokens": usage.cache_write_1h_input_tokens if usage else 0,+ "cache_write_30m_input_tokens": usage.cache_write_30m_input_tokens if usage else 0,+ "cache_write_12h_input_tokens": usage.cache_write_12h_input_tokens if usage else 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": usage.cache_write_ttl_uncaptured_reports if usage else 0,}@@ -1491,6 +1530,8 @@ class BoundedUsageLedger:if existing is None:rows[_row_key(row)] = rowcontinue+ if existing.get("_legacy_cache_write_shape") and not row.get("_legacy_cache_write_shape"):+ existing.pop("_legacy_cache_write_shape", None)_accumulate(existing, row)existing["last_metered_at"] = _newer_timestamp(existing["last_metered_at"],@@ -1567,7 +1608,7 @@ class BoundedUsageLedger:# call. Preserve the existing degradation witness on a survivor so# reopening cannot publish the retained row as complete history.retained = [{**row, "history_degraded": True} for row in retained]- write_state_document(self.path, sorted(retained, key=_row_key))+ write_state_document(self.path, [_persistable_row(row) for row in sorted(retained, key=_row_key)])def record(self,@@ -1666,6 +1707,8 @@ class BoundedUsageLedger:if existing is None:rows[_row_key(increment)] = incrementelse:+ if existing.get("_legacy_cache_write_shape"):+ existing.pop("_legacy_cache_write_shape", None)_accumulate(existing, increment)existing["last_metered_at"] = _newer_timestamp(existing["last_metered_at"],@@ -2444,6 +2487,15 @@ class UsageCall:cache_write_1h_input_tokens=sum(report.cache_write_1h_input_tokens for report in reports),+ cache_write_30m_input_tokens=sum(+ report.cache_write_30m_input_tokens for report in reports+ ),+ cache_write_12h_input_tokens=sum(+ report.cache_write_12h_input_tokens for report in reports+ ),+ cache_write_ttl_uncaptured_reports=sum(+ report.cache_write_ttl_uncaptured_reports for report in reports+ ),)return replace(self,diff --git a/docs/plans/agent-core-contracts/context.md b/docs/plans/agent-core-contracts/context.mdindex a98c72454..35b1ca085 100644--- a/docs/plans/agent-core-contracts/context.md+++ b/docs/plans/agent-core-contracts/context.md@@ -149,22 +149,25 @@ before a retry alike:as overflow, goes straight to the drop (§8 c, §10).The cache lifetime is the documented lifetime of the cache mode Vibey requests for the conversation, where clearable-results live, resolved on every request from the route's provider, protocol, and whole model id-(`harness/context.py`, `CACHE_TTLS`):+results live, resolved on every request from the route's provider, protocol, whole model id, and validated Model Hub+route override (`harness/context.py`, `CACHE_TTLS`):| Route | Lifetime || --- | --- || provider `anthropic` on the Anthropic protocol: the message breakpoints' `cache_control` is ephemeral, with no `ttl` | 300 s, refreshed on use |-| provider `openai`, a model id `gpt-<major>[.<minor>][-<suffix>]` from GPT-5.6: `prompt_cache_options.ttl` is 30 minutes, its default and only value, and Vibey sends none | 1,800 s |-| any other route, or one not identified unambiguously (older OpenAI models, other vendors on either protocol, relays) | 3,600 s |+| provider `openai`, protocol `openai_responses`, and a model id `gpt-<major>[.<minor>][-<suffix>]` from GPT-5.6: `prompt_cache_options.ttl` defaults to 30 minutes; an explicit route override may request `30m` or the opt-in `12h` mode | 1,800 s by default |+| any other route, or one not identified unambiguously (older OpenAI models, `openai_chat`, other vendors, relays) | 3,600 s |+| a nonempty route's validated `cache_ttl` override | the configured 5m, 30m, 1h, or 12h estimate; official OpenAI Responses GPT-5.6+ routes accept explicit `30m` or `12h` wire modes |-Clearing a warm cache forces a full-price re-read of the context, while skipping a clear on a cold one only keeps+Earlier supported OpenAI models may expose a separate policy-dependent `prompt_cache_retention` mode (`in_memory` or `24h`), but Avibe does not infer or send that option; those routes remain on the conservative built-in estimate unless a route capability explicitly supports it. The official 12-hour Responses mode has a 2.5x cache-write rate versus 1.25x for the 30-minute default, while reads use the same cached-input rate; Avibe sends that opt-in only on confirmed official GPT-5.6+ Responses routes and meters the two write lifetimes separately. Clearing a warm cache forces a full-price re-read of the context, while skipping a clear on a cold one only keepssome old output, so an unknown lifetime counts as an hour, and relays and subscription sources that keep a shorterone err toward warm. The idle time is the route's own cache's: it runs from the later of the latest model call's endand the latest response's commit served by the same provider and model as the request's route (the protocol thatreaches the gateway, converted or not, does not change the cache), which overstates warmth by a response's duration,-the same safe direction; another route's use never refreshes it. A route with no use in the Session yet takes the-latest use of any route.+the same safe direction; another route's use never refreshes it. Response rows carry the served Source identity and+provider/model origin, but this C-9 clock intentionally keys by provider/model, so Sources with the same provider/model+share one clock; a route override is route-wide, not a claim that those Sources have independent cache clocks. A route+with no use in the Session yet takes the latest use of any route.A request the provider rejects as overflow (`ProviderError.kind == "overflow"`, classified by`ai/errors.is_overflow_message`, HTTP 413, and `context_length_exceeded`) before anything was streamed, and with no@@ -530,7 +533,10 @@ ends the run `context_exhausted`, as in P1. The adapter supplies the following;`modules/agents/vibey` (`agent.py`, `context.py`, `store.py`), and every Turn of it runs with a `ContextConfig`.- The route's identity: its endpoint's `provider`, `protocol`, and `model_id` (the hop's `provider` and- `runtime_model`), from which the loop resolves the cache lifetime on every request (§3); nothing configures it.+ `runtime_model`), from which the loop resolves the cache lifetime on every request (§3). Model Hub may carry a+ validated route-wide `cache_ttl`; it is a route-wide override, not a per-Source clock. Canonical response rows and+ served-hop metadata do carry the credential-free Source identity, but the C-9 cache clock intentionally remains keyed+ by provider/model, so same-provider/model Sources share it.- The limits (§1): the route's capabilities come from the Model Hub model definition the user edits(`context_window`, `max_output_tokens`; `input_limit` stays unknown until Model Hub stores one, so `L_in = W`), andthe Agent asks for `min(max_output_tokens, floor(W / 4))` (the maximum 8,192 when unknown) on every hop it resolves,diff --git a/docs/plans/agent-core-contracts/conversion-tables.md b/docs/plans/agent-core-contracts/conversion-tables.mdindex ab653d9cb..5039d6d2f 100644--- a/docs/plans/agent-core-contracts/conversion-tables.md+++ b/docs/plans/agent-core-contracts/conversion-tables.md@@ -365,16 +365,19 @@ reasoning follows the canonical optional-field rule.| Documented wire field | Canonical mapping or ignore policy || --- | --- |-| `input_tokens` | `input_tokens = max(0, input_tokens - cache_read_tokens - cache_write_tokens)` |+| `input_tokens` | `input_tokens`, inclusive of cached reads and cache writes; pricing derives ordinary input as `input_tokens - cache_read_tokens - cache_write_tokens` || `input_tokens_details` | Input breakdown container; not itself a count || `input_tokens_details.cached_tokens` | `cache_read_tokens`, default zero || `input_tokens_details.cache_write_tokens` | `cache_write_tokens`, default zero; distinct from cache reads |+| `input_tokens_details.cache_write_tokens_details.ttl_30m_tokens` | `cache_write_30m_input_tokens`; disjoint from the 12h count |+| `input_tokens_details.cache_write_tokens_details.ttl_12h_tokens` | `cache_write_12h_input_tokens`; disjoint from the 30m count || `output_tokens` | `output_tokens`, inclusive of reasoning || `output_tokens_details` | Output decomposition container; not itself a count || `output_tokens_details.reasoning_tokens` | `reasoning_tokens`; absent field is `None`. Accepted compatible null counter normalizes to zero, matching Pi. || `total_tokens` | Ignored: redundant inclusive input + output; canonical components already preserve the total |-Fixture: actual pinned-Pi projection `10 - 3 - 2 = 5`, output `4`, reasoning+Fixture: actual pinned-Pi projection `12 - 3 - 2 = 7` ordinary input, with the+lifetime write breakdown retained separately; output `4`, reasoning`2`; the full documented object also supplies `total_tokens: 14`. Pi's oldChat source comment calls cache writes a compatibility extension; the currentofficial Chat and Responses schemas fetched above now document that counter.diff --git a/docs/plans/agent-core-contracts/hop-resolution.schema.json b/docs/plans/agent-core-contracts/hop-resolution.schema.jsonindex f696172b9..a2108ebb9 100644--- a/docs/plans/agent-core-contracts/hop-resolution.schema.json+++ b/docs/plans/agent-core-contracts/hop-resolution.schema.json@@ -55,6 +55,14 @@"type": "string","description": "Vendor identity of the primary hop; becomes `origin.provider` unless the served-hop report differs."},+ "cache_ttl": {+ "enum": ["5m", "30m", "1h", "12h", null],+ "description": "Validated Model Hub route-local cache lifetime override. Unset uses C-9's built-in provider estimate. Confirmed official OpenAI Responses GPT-5.6+ routes may explicitly request 30m or 12h; other providers and relays keep their supported semantics."+ },+ "cache_ttl_wire": {+ "type": "boolean",+ "description": "True only when the adapter may send cache_ttl as a provider-specific request option."+ },"request_headers": {"type": "object","additionalProperties": {diff --git a/docs/plans/model-hub-contracts/agent-chain.schema.json b/docs/plans/model-hub-contracts/agent-chain.schema.jsonindex 92ae038c7..43cbdcedf 100644--- a/docs/plans/model-hub-contracts/agent-chain.schema.json+++ b/docs/plans/model-hub-contracts/agent-chain.schema.json@@ -19,6 +19,10 @@"required": ["hops"],"additionalProperties": false,"properties": {+ "cache_ttl": {+ "enum": ["5m", "30m", "1h", "12h", null],+ "description": "Optional route-wide C-9 cache lifetime override; unset uses the built-in estimate. Confirmed official OpenAI Responses GPT-5.6+ routes may request 30m or 12h."+ },"hops": {"type": "array","minItems": 1,diff --git a/docs/plans/model-hub-contracts/agent-supply.schema.json b/docs/plans/model-hub-contracts/agent-supply.schema.jsonindex 922909878..ad0c78a47 100644--- a/docs/plans/model-hub-contracts/agent-supply.schema.json+++ b/docs/plans/model-hub-contracts/agent-supply.schema.json@@ -114,6 +114,10 @@"required": ["hops"],"additionalProperties": false,"properties": {+ "cache_ttl": {+ "enum": ["5m", "30m", "1h", null],+ "description": "Optional route-wide C-9 cache lifetime override; unset uses the built-in estimate."+ },"hops": {"type": "array","minItems": 1,diff --git a/docs/plans/model-hub-contracts/api.md b/docs/plans/model-hub-contracts/api.mdindex 2a35cf5fc..703058c0d 100644--- a/docs/plans/model-hub-contracts/api.md+++ b/docs/plans/model-hub-contracts/api.md@@ -63,9 +63,9 @@ runtime open. Once models are configured it participates in the runtime Stop gua| GET `/api/models/catalog/models-dev?query=<text>` | → `{matches: ModelsDevMatch[]}` | Read-only metadata lookup through the server-owned conditional cache. Results keep the shipped provider fields, deduplicate aggregator copies by model id, rank first-party matches first, add `first_party`, derive `native_protocol` from the model id's last path segment through the vendor map, cap results at 8, and never persist automatically. || GET `/api/models/agents/<backend>/chains` | → `{chains: AgentChain[]}` | Hub only. Returns the complete Overview model set in menu order, followed by a selected model or configured Route not already present. All members share one config snapshot and observation time. Direct returns the documented `direct_mode` error. || GET `/api/models/agents/<backend>/chain?model=<id>` | → `{chain: AgentChain}` | Hub only. Direct returns the documented `direct_mode` error. |-| PUT `/api/models/agents/<backend>/chain?model=<id>` | `{hops: RouteHop[], force?: boolean, would_remove_hops?: RouteHopRef[], would_interrupt?: SupplyGap[]}` → guarded `409` or `{chain, removed_hops, interrupted}` | Nonempty hops save an exact manual override, including equal-to-automatic arrays. Empty hops remain accepted and use DELETE Restore semantics with identical exact effective-removal/supply guards. New pairs validate canonical ids, Source eligibility/existence and retirement; API-key pairs do not require inventory membership, while subscriptions retain existing membership admission/stale-hop retention. Only nonempty replacement uses the protected-supply-only `mutation.route_replace` guard. |+| PUT `/api/models/agents/<backend>/chain?model=<id>` | `{hops: RouteHop[], cache_ttl?: "5m" | "30m" | "1h" | "12h" | null, force?: boolean, would_remove_hops?: RouteHopRef[], would_interrupt?: SupplyGap[]}` → guarded `409`, `422 cache_ttl_unsupported`, or `{chain, removed_hops, interrupted}` | Nonempty hops save an exact manual override, including equal-to-automatic arrays. On Vibey routes, `cache_ttl` is a route-wide C-9 clearing override; omitted/null uses the built-in estimate. It is rejected on non-Vibey routes. Confirmed official OpenAI Responses GPT-5.6+ routes may explicitly request the 30m default or opt into 12h; both are wired as `prompt_cache_options.ttl` and usage accounting keeps their write lifetimes separate. Custom relays never receive OpenAI-specific cache options. Empty hops remain accepted and use DELETE Restore semantics with identical exact effective-removal/supply guards. New pairs validate canonical ids, Source eligibility/existence and retirement; API-key pairs do not require inventory membership, while subscriptions retain existing membership admission/stale-hop retention. Only nonempty replacement uses the protected-supply-only `mutation.route_replace` guard. || DELETE `/api/models/agents/<backend>/chain?model=<id>` | optional `{force?: boolean, would_remove_hops?: RouteHopRef[], would_interrupt?: SupplyGap[]}` → guarded `409` or `{chain, removed_hops, interrupted}` | `mutation.route_restore` removes the key and recomputes defaults; absent key is idempotent. Guard actual effective removals and supply loss. |-| POST `/api/models/agents/<backend>/chain/preview?model=<id>` | `{manual_override: null \| {hops: RouteHop[]}}` → `{chain: AgentChain}` | Accepts empty hops and normalizes them to null before the shared planner evaluates isolated draft config. Output manual_override is nonempty or null; effective chain/origin follows inheritance. No persistence, events, engine startup/sync, credentials or egress, including when runtime is stopped. |+| POST `/api/models/agents/<backend>/chain/preview?model=<id>` | `{manual_override: null \| {hops: RouteHop[], cache_ttl?: "5m" | "30m" | "1h" | "12h" | null}}` → `{chain: AgentChain}` | Accepts empty hops and normalizes them to null before the shared planner evaluates isolated draft config. On Vibey routes, the optional route-wide cache override is validated with the same provider/route rules as PUT; official OpenAI Responses GPT-5.6+ accepts explicit 30m or 12h, while relays never receive OpenAI-specific cache options. Other backends reject the field. Output manual_override is nonempty or null; effective chain/origin follows inheritance. No persistence, events, engine startup/sync, credentials or egress, including when runtime is stopped. || POST `/api/models/agents/<backend>/probe` | `{model?}` → `{probe: ProbeResult}` | Hub only. Direct returns the same `direct_mode` error. || GET `/api/models/agents/<backend>/provenance?model=<id>` | → `{provenance: TurnProvenance \| null}` | On-demand read of the most recently persisted retained record for this exact backend and canonical catalog model, regardless of outcome. Validates backend/model; absent history is null. Uses only the existing bounded store and never starts or syncs the engine. No history field is added to AgentChain. || GET `/api/models/events?limit=<n>&before=<id>` | → `{events: ResolutionEvent[]}` | Bounded source-resolution feed. |@@ -1732,12 +1732,16 @@ so one model is one row rather than one row per spelling.Cache writes are metered separately from input served from cache.`cache_write_input_tokens` is the subset of `input_tokens` written to the promptcache (Anthropic `cache_creation_input_tokens`), disjoint from-`cached_input_tokens`, and `cache_write_1h_input_tokens` is the part of it written-with the one-hour lifetime (`cache_creation.ephemeral_1h_input_tokens`). OpenAI-protocols report no cache writes, so both are zero there. The fields are additive:-a ledger row written before they existed reads them as zero and counts its token-reports in `cache_write_uncaptured_reports`, so a consumer can tell "no cache-writes" from "cache writes not captured". No stored row is rewritten.+`cached_input_tokens`. Anthropic's `cache_write_1h_input_tokens` is the part+written with the one-hour lifetime (`cache_creation.ephemeral_1h_input_tokens`).+Official OpenAI Responses reports disjoint `cache_write_30m_input_tokens` and+`cache_write_12h_input_tokens`; those sum to its documented+`cache_write_tokens` total when the evidence is complete. Missing or invalid+OpenAI totals/breakdowns remain visible in `cache_write_ttl_uncaptured_reports`+and keep the valuation a lower bound; no TTL is inferred from the configured+request default. The fields are additive: released rows read missing new fields+as zero while preserving their existing truthful Anthropic counters, and an+untouched released row is not rewritten in place.### API-price valuationdiff --git a/docs/plans/model-hub-contracts/hop-resolution.schema.json b/docs/plans/model-hub-contracts/hop-resolution.schema.jsonindex ff5a50de6..ccaab7e4e 100644--- a/docs/plans/model-hub-contracts/hop-resolution.schema.json+++ b/docs/plans/model-hub-contracts/hop-resolution.schema.json@@ -20,6 +20,14 @@"description": "The primary hop Source's credential-free identity (identity_digest), from the snapshot its origin came from. The consumer replays opaque payloads only to a hop of the identity that served them."},"provider": { "type": "string" },+ "cache_ttl": {+ "enum": ["5m", "30m", "1h", "12h", null],+ "description": "Validated Model Hub route-local cache lifetime override; unset uses the built-in C-9 estimate. Confirmed official OpenAI Responses GPT-5.6+ routes may explicitly request 30m or 12h; relays do not receive OpenAI-specific cache options."+ },+ "cache_ttl_wire": {+ "type": "boolean",+ "description": "True only when the adapter may send cache_ttl as a provider-specific request option."+ },"request_headers": { "type": "object", "additionalProperties": { "type": "string" } },"capabilities": {"type": "object",diff --git a/docs/plans/model-hub-contracts/usage-summary.schema.json b/docs/plans/model-hub-contracts/usage-summary.schema.jsonindex 0af37339d..3ae2f70b2 100644--- a/docs/plans/model-hub-contracts/usage-summary.schema.json+++ b/docs/plans/model-hub-contracts/usage-summary.schema.json@@ -182,10 +182,22 @@"$ref": "#/definitions/Count","description": "Subset of cache_write_input_tokens written with the one-hour cache lifetime (Anthropic `cache_creation.ephemeral_1h_input_tokens`); the rest used the five-minute lifetime."},+ "cache_write_30m_input_tokens": {+ "$ref": "#/definitions/Count",+ "description": "OpenAI Responses cache-write tokens reported for the 30-minute lifetime. This counter is distinct from Anthropic's one-hour counter."+ },+ "cache_write_12h_input_tokens": {+ "$ref": "#/definitions/Count",+ "description": "OpenAI Responses cache-write tokens reported for the 12-hour lifetime. The 30m and 12h counters are disjoint and together must not exceed cache_write_input_tokens."+ },"cache_write_uncaptured_reports": {"$ref": "#/definitions/Count","description": "Subset of token_reports metered before cache writes were captured. Their cache writes, if any, are inside input_tokens but not in cache_write_input_tokens."},+ "cache_write_ttl_uncaptured_reports": {+ "$ref": "#/definitions/Count",+ "description": "Token reports for OpenAI Responses rows whose total cache-write count or 30m/12h lifetime breakdown was missing or invalid. These reports remain a lower bound and no TTL is inferred from the request default."+ },"api_cost_usd": {"description": "What this usage would cost at the vendor's list API price, in `pricing.currency`, at the current price table — never the price in force when the call ran. A valuation for comparison, never an amount charged. Present exactly when `pricing` is. Usage whose model has no price is left out and counted in excluded_tokens, never priced as zero.","type": "number",@@ -262,9 +274,18 @@"cache_write_1h_input_tokens": {"$ref": "#/definitions/Counters/properties/cache_write_1h_input_tokens"},+ "cache_write_30m_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_30m_input_tokens"+ },+ "cache_write_12h_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_12h_input_tokens"+ },"cache_write_uncaptured_reports": {"$ref": "#/definitions/Counters/properties/cache_write_uncaptured_reports"},+ "cache_write_ttl_uncaptured_reports": {+ "$ref": "#/definitions/Counters/properties/cache_write_ttl_uncaptured_reports"+ },"api_cost_usd": {"$ref": "#/definitions/Counters/properties/api_cost_usd"},@@ -423,9 +444,18 @@"cache_write_1h_input_tokens": {"$ref": "#/definitions/Counters/properties/cache_write_1h_input_tokens"},+ "cache_write_30m_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_30m_input_tokens"+ },+ "cache_write_12h_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_12h_input_tokens"+ },"cache_write_uncaptured_reports": {"$ref": "#/definitions/Counters/properties/cache_write_uncaptured_reports"},+ "cache_write_ttl_uncaptured_reports": {+ "$ref": "#/definitions/Counters/properties/cache_write_ttl_uncaptured_reports"+ },"api_cost_usd": {"$ref": "#/definitions/Counters/properties/api_cost_usd"},@@ -483,9 +513,18 @@"cache_write_1h_input_tokens": {"$ref": "#/definitions/Counters/properties/cache_write_1h_input_tokens"},+ "cache_write_30m_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_30m_input_tokens"+ },+ "cache_write_12h_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_12h_input_tokens"+ },"cache_write_uncaptured_reports": {"$ref": "#/definitions/Counters/properties/cache_write_uncaptured_reports"},+ "cache_write_ttl_uncaptured_reports": {+ "$ref": "#/definitions/Counters/properties/cache_write_ttl_uncaptured_reports"+ },"api_cost_usd": {"$ref": "#/definitions/Counters/properties/api_cost_usd"},@@ -608,9 +647,18 @@"cache_write_1h_input_tokens": {"$ref": "#/definitions/Counters/properties/cache_write_1h_input_tokens"},+ "cache_write_30m_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_30m_input_tokens"+ },+ "cache_write_12h_input_tokens": {+ "$ref": "#/definitions/Counters/properties/cache_write_12h_input_tokens"+ },"cache_write_uncaptured_reports": {"$ref": "#/definitions/Counters/properties/cache_write_uncaptured_reports"},+ "cache_write_ttl_uncaptured_reports": {+ "$ref": "#/definitions/Counters/properties/cache_write_ttl_uncaptured_reports"+ },"api_cost_usd": {"$ref": "#/definitions/Counters/properties/api_cost_usd"},@@ -675,7 +723,10 @@"output_tokens": 4120,"cache_write_input_tokens": 20100,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": 0,"api_cost_usd": 0.43723,"excluded_tokens": 0,"api_cost_lower_bound": false@@ -702,7 +753,10 @@"output_tokens": 4120,"cache_write_input_tokens": 20100,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": 0,"api_cost_usd": 0.43723,"excluded_tokens": 0,"api_cost_lower_bound": false,@@ -711,7 +765,10 @@],"cache_write_input_tokens": 20100,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": 0,"api_cost_usd": 0.43723,"excluded_tokens": 0,"api_cost_lower_bound": false@@ -727,7 +784,10 @@"output_tokens": 4120,"cache_write_input_tokens": 20100,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": 0,"api_cost_usd": 0.43723,"excluded_tokens": 0,"api_cost_lower_bound": falsediff --git a/modules/agents/model_hub.py b/modules/agents/model_hub.pyindex bd2caf6f2..f6e00255f 100644--- a/modules/agents/model_hub.py+++ b/modules/agents/model_hub.py@@ -46,6 +46,7 @@ from core.handlers.model_hub.provenance import ()from core.handlers.model_hub.resolver import (BackendName,+ CacheTtl,ModelHubTurnResolution,resolve_model_hub_turn,source_after_cooldown_recovery,@@ -129,6 +130,11 @@ class ModelHubLaunch:provider: Optional[str] = Noneinput_limit: Optional[int] = Nonesupports_images: Optional[bool] = None+ # Vibey only: the route-local prompt-cache lifetime override. Canonical+ # response rows and served-hop metadata carry Source identity, but the C-9+ # clock intentionally remains keyed by provider/model rather than Source.+ cache_ttl: CacheTtl | None = None+ cache_ttl_wire: bool = False# Vibey only: each enabled hosted tool's mode, declaration, executor and replay.hosted_tools: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)# Vibey only: the Source's credential-free identity, from the snapshot its origin came from (C-6).@@ -154,6 +160,8 @@ class ModelHubLaunch:"runtime_model": self.runtime_model,"source_id": self.source_id,"source_identity": self.source_identity,+ "cache_ttl": self.cache_ttl,+ "cache_ttl_wire": self.cache_ttl_wire,"provider": self.provider,"request_headers": dict(self.gateway_request_metadata),"capabilities": {@@ -1333,6 +1341,8 @@ class ModelHubRuntimeRouter:reasoning_efforts=reasoning_efforts,protocol=source.protocol,provider=source.vendor,+ cache_ttl=resolution.cache_ttl,+ cache_ttl_wire=resolution.cache_ttl_wire,supports_images=("image" in backend_model.input_modalitiesif backend_model is not None and backend_model.input_modalitiesdiff --git a/modules/agents/vibey/models.py b/modules/agents/vibey/models.pyindex c4c3bb54d..1b713e908 100644--- a/modules/agents/vibey/models.py+++ b/modules/agents/vibey/models.py@@ -191,6 +191,19 @@ def selection_from_hop(hop: Mapping[str, Any], *, gateway_base_url: Optional[strraise HopResolutionError("a google hop needs the gateway prefix to call Chat Completions")protocol, base_url = "openai_chat", f"{gateway_base_url.rstrip('/')}/v1"origin_api = original_protocol if original_protocol != protocol else None+ raw_cache_ttl = hop.get("cache_ttl")+ if raw_cache_ttl is not None and (+ not isinstance(raw_cache_ttl, str)+ or raw_cache_ttl not in {"5m", "30m", "1h", "12h"}+ ):+ raise HopResolutionError("hop cache_ttl is invalid")+ cache_ttl = raw_cache_ttl+ raw_cache_ttl_wire = hop.get("cache_ttl_wire", False)+ if not isinstance(raw_cache_ttl_wire, bool):+ raise HopResolutionError("hop cache_ttl_wire is invalid")+ cache_ttl_wire = raw_cache_ttl_wire+ if cache_ttl_wire and cache_ttl not in {"30m", "12h"}:+ raise HopResolutionError("hop cache_ttl_wire requires 30m or 12h")endpoint = ModelEndpoint(protocol=protocol,base_url=base_url,@@ -198,6 +211,8 @@ def selection_from_hop(hop: Mapping[str, Any], *, gateway_base_url: Optional[strtoken=hop["token"],request_headers=dict(headers),provider=hop["provider"],+ cache_ttl=cache_ttl,+ cache_ttl_wire=cache_ttl_wire,source_id=hop["source_id"],source_identity=hop["source_identity"],hosted_tools=hosted_tools,diff --git a/tests/agent_core/agent/test_compaction.py b/tests/agent_core/agent/test_compaction.pyindex 16eb840e7..6d9817a6c 100644--- a/tests/agent_core/agent/test_compaction.py+++ b/tests/agent_core/agent/test_compaction.py@@ -1591,10 +1591,14 @@ async def test_a_converted_route_cache_is_its_upstream_provider_and_model():assert len(await routed_turn(store, now, GEMINI, [[Done(assistant("five"))]], "turn-5", GEMINI_SERVED)) == 4-async def test_pressure_clearing_runs_on_a_warm_cache():[email protected]("cache_ttl", [None, "1h", "12h"])+async def test_pressure_clearing_runs_on_a_warm_cache(cache_ttl):# From 0.8 T old results clear whatever the cache's lifetime (section 3): on this window T = 59,904, and nine# results of 6,000 tokens hold 0.9 T. The third Turn is the first whose old results are not protected.- route = ModelSelection(ENDPOINT, replace(SELECTION.capabilities, context_window=72_000, input_limit=None))+ route = ModelSelection(+ replace(ENDPOINT, cache_ttl=cache_ttl),+ replace(SELECTION.capabilities, context_window=72_000, input_limit=None),+ )script = [*_long_context(9), *([Done(assistant(word))] for word in ("one", "two", "three"))]model = Model(script, [[Done(assistant(CHECKPOINT))]])agent = make_agent(diff --git a/tests/agent_core/agent/test_context.py b/tests/agent_core/agent/test_context.pyindex 7fd480e99..b73c136ab 100644--- a/tests/agent_core/agent/test_context.py+++ b/tests/agent_core/agent/test_context.py@@ -534,7 +534,7 @@ def test_a_checkpoint_or_another_route_invalidates_the_anchor():("anthropic", "anthropic", "claude-opus-5-5", 300), # message breakpoints: ephemeral, no ttl("openai_responses", "openai", "gpt-6-astra", 1_800),("openai_responses", "openai", "gpt-6.1-sol", 1_800),- ("openai_chat", "openai", "gpt-5.6-mini", 1_800),+ ("openai_chat", "openai", "gpt-5.6-mini", 3_600), # OpenAI cache retention is official Responses-only("openai_responses", "openai", "gpt-5.5", 3_600), # before GPT-5.6: in-memory, 5 minutes to an hour("openai_responses", "openai", "gpt-4o", 3_600),("openai_responses", "openai", "o3", 3_600),@@ -549,6 +549,19 @@ def test_a_route_cache_lives_as_long_as_its_family_documents_else_an_hour(protocassert cache_ttl_s(ModelEndpoint(protocol, "http://model.invalid", model, "", provider=provider)) == lifetime[email protected]("cache_ttl, expected", [("1h", 3_600), ("12h", 43_200)])+def test_a_route_cache_override_wins_over_provider_family(cache_ttl, expected):+ endpoint = ModelEndpoint(+ "openai_responses",+ "http://model.invalid",+ "gpt-6-astra",+ "",+ provider="openai",+ cache_ttl=cache_ttl,+ )+ assert cache_ttl_s(endpoint) == expected++def _random_rows(seed: int) -> list[ContextEntry]:rng = random.Random(seed)rows = Rows()diff --git a/tests/agent_core/ai/test_provider_adapters.py b/tests/agent_core/ai/test_provider_adapters.pyindex 998a2fc3c..28fa25077 100644--- a/tests/agent_core/ai/test_provider_adapters.py+++ b/tests/agent_core/ai/test_provider_adapters.py@@ -76,6 +76,26 @@ def _request()+ ("cache_ttl", "cache_ttl_wire", "expected"),+ [+ (None, False, None),+ ("12h", True, {"ttl": "12h"}),+ ("30m", False, None), # relays may keep the local estimate, never OpenAI's wire option+ ],+)+def test_responses_prompt_cache_retention_is_wired_only_when_model_hub_confirms_it(+ cache_ttl: str | None, cache_ttl_wire: bool, expected: dict[str, str] | None,+) -> None:+ request = _request("openai_responses", model_id="gpt-6-astra")+ request = replace(+ request,+ endpoint=replace(request.endpoint, cache_ttl=cache_ttl, cache_ttl_wire=cache_ttl_wire),+ )+ payload = build_responses_payload(request, request.messages)+ assert payload.get("prompt_cache_options") == expected++def test_registry_exposes_only_v1_protocols() -> None:assert set(ADAPTERS) == {"anthropic", "openai_chat", "openai_responses"}with pytest.raises(ValueError, match="unsupported provider protocol: google"):diff --git a/tests/test_model_hub_api.py b/tests/test_model_hub_api.pyindex 57bcd709f..4f974e291 100644--- a/tests/test_model_hub_api.py+++ b/tests/test_model_hub_api.py@@ -500,6 +500,45 @@ def _set_claude_route_fixture(return hops+def test_vibey_route_cache_ttl_persists_30m_and_12h(tmp_path):+ service, store, _ = _service(tmp_path)+ model_id = "gpt-6-astra"+ source = ModelHubSourceConfig(+ id="src_openai001",+ kind="api_key",+ vendor="openai",+ display_name="OpenAI",+ protocol="openai_responses",+ supply_channel="hub",+ billing="metered",+ state=ModelHubSourceStateConfig(status="standby"),+ models=[ModelHubModelConfig(id=model_id, provenance="discovered")],+ credential_ref="cred_openai001",+ )+ store.config.sources = [source]+ agent = store.config.agents["vibey"]+ agent.mode = "hub"+ agent.models = [ModelHubBackendModelConfig(id=model_id)]+ agent.sources.order = [source.id]+ service._engine_synced = True++ saved = asyncio.run(service.set_agent_chain(+ "vibey",+ model_id,+ {"hops": [{"source_id": source.id, "model_id": model_id}], "cache_ttl": "30m"},+ ))+ assert saved["chain"]["manual_override"]["cache_ttl"] == "30m"+ assert store.config.agents["vibey"].routes[model_id].cache_ttl == "30m"++ saved = asyncio.run(service.set_agent_chain(+ "vibey",+ model_id,+ {"hops": [{"source_id": source.id, "model_id": model_id}], "cache_ttl": "12h"},+ ))+ assert saved["chain"]["manual_override"]["cache_ttl"] == "12h"+ assert store.config.agents["vibey"].routes[model_id].cache_ttl == "12h"++async def _create_source(service: ModelHubService, payload: dict) -> dict:return (await service.create_source(payload))["source"]diff --git a/tests/test_model_hub_config.py b/tests/test_model_hub_config.pyindex be809e02d..1eee29905 100644--- a/tests/test_model_hub_config.py+++ b/tests/test_model_hub_config.py@@ -1553,7 +1553,7 @@ def test_model_hub_config_round_trip_and_serializer_completeness(monkeypatch, tmassert serialized_source["models"][0].get("retired", False) is False, labelassert agent_fields == set(serialized_hub["agents"]["claude"]), labelassert agent_sources_fields == set(serialized_hub["agents"]["claude"]["sources"]), label- assert route_fields == set(ModelHubRouteConfig().to_payload()), label+ assert route_fields - {"cache_ttl"} == set(ModelHubRouteConfig().to_payload()), labelassert menu_fields == set(serialized_hub["agents"]["opencode"]["menu"]), labelstale_hub_payload = json.loads(json.dumps(api_payload["model_hub"]))@@ -2977,6 +2977,34 @@ def test_agent_source_orders_validate_existence_eligibility_and_uniqueness():ModelHubConfig.from_payload(ineligible)+def test_route_cache_ttl_is_optional_and_closed():+ route = ModelHubRouteConfig.from_payload(+ {+ "hops": [{"source_id": "src_same0001", "model_id": "model-a"}],+ "cache_ttl": "1h",+ }+ )+ assert route.cache_ttl == "1h"+ route_12h = ModelHubRouteConfig.from_payload(+ {+ "hops": [{"source_id": "src_same0001", "model_id": "model-a"}],+ "cache_ttl": "12h",+ }+ )+ assert route_12h.cache_ttl == "12h"+ assert "cache_ttl" not in ModelHubRouteConfig.from_payload(+ {"hops": [{"source_id": "src_same0001", "model_id": "model-a"}]}+ ).to_payload()+ for value in ("", "24h", 3600, True):+ with pytest.raises(ValueError, match="cache_ttl"):+ ModelHubRouteConfig.from_payload(+ {+ "hops": [{"source_id": "src_same0001", "model_id": "model-a"}],+ "cache_ttl": value,+ }+ )++def test_route_hops_allow_one_source_to_supply_distinct_models():route = ModelHubRouteConfig.from_payload({diff --git a/tests/test_model_hub_pricing.py b/tests/test_model_hub_pricing.pyindex 3ff1cfe24..b03aa99c4 100644--- a/tests/test_model_hub_pricing.py+++ b/tests/test_model_hub_pricing.py@@ -111,10 +111,12 @@ def test_model_price_reads_models_dev_cost_and_fills_missing_cache_prices():"""MH-PRICE-001: A missing cache price is input; a one-hour cache write is twice input unless listed."""assert model_price({"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}) == ModelPrice(- input=5, output=25, cache_read=0.5, cache_write=6.25, cache_write_1h=10, charges_cache_writes=True+ input=5, output=25, cache_read=0.5, cache_write=6.25, cache_write_1h=10,+ cache_write_30m=6.25, cache_write_12h=12.5, charges_cache_writes=True)assert model_price({"input": 2, "output": 6}) == ModelPrice(- input=2, output=6, cache_read=2, cache_write=2, cache_write_1h=4+ input=2, output=6, cache_read=2, cache_write=2, cache_write_1h=4,+ cache_write_30m=2.5, cache_write_12h=5)assert model_price({"input": 2, "output": 6, "cache_write_1h": 3}).cache_write_1h == 3for bad in (None, {}, {"input": 1}, {"input": -1, "output": 1}, {"input": True, "output": 1},@@ -244,6 +246,187 @@ def test_usage_metered_before_cache_writes_were_captured_is_a_lower_bound():assert row_cost(row, model_price({"input": 2, "output": 6})).api_cost_lower_bound is False+++def test_openai_mixed_lifetime_usage_is_parsed_persisted_and_priced(tmp_path):+ """OpenAI's documented example survives the wire, ledger, read-back, and list-price valuation."""++ payload = {+ "usage": {+ "input_tokens": 12_000,+ "input_tokens_details": {+ "cached_tokens": 4_000,+ "cache_write_tokens": 7_000,+ "cache_write_tokens_details": {+ "ttl_30m_tokens": 3_000,+ "ttl_12h_tokens": 4_000,+ },+ },+ "output_tokens": 0,+ }+ }+ usage = extract_protocol_usage("openai_responses", payload)+ assert usage == ProtocolUsageReport.of(+ input_tokens=12_000,+ cached_input_tokens=4_000,+ output_tokens=0,+ cache_write_input_tokens=7_000,+ cache_write_30m_input_tokens=3_000,+ cache_write_12h_input_tokens=4_000,+ )++ now = datetime(2026, 10, 26, 12, 0, tzinfo=timezone.utc)+ path = tmp_path / "usage.json"+ ledger = BoundedUsageLedger(path, now=lambda: now)+ ledger.record_many([UsageCall("src_openai", "gpt-5.6-oracle", usage, now)])+ persisted = json.loads(path.read_text(encoding="utf-8"))[0]+ assert persisted["cache_write_input_tokens"] == 7_000+ assert persisted["cache_write_30m_input_tokens"] == 3_000+ assert persisted["cache_write_12h_input_tokens"] == 4_000+ table = PriceTable(+ catalog={"openai": {"models": {"gpt-5.6-oracle": {"cost": {"input": 1, "output": 2, "cache_read": 0.1}}}}},+ vendor_map=VENDOR_MAP,+ overrides={},+ price_table_date="2026-10-26",+ )+ summary = ledger.summary(+ days=1,+ now=now,+ identities=[SourceIdentity("src_openai", "OpenAI", ["gpt-5.6-oracle"])],+ prices=table,+ )+ assert summary["totals"]["cache_write_30m_input_tokens"] == 3_000+ assert summary["totals"]["cache_write_12h_input_tokens"] == 4_000+ assert summary["totals"]["api_cost_usd"] == pytest.approx(0.01515)+ assert summary["totals"]["api_cost_lower_bound"] is False+ tiered = model_price({+ "input": 1,+ "output": 2,+ "cache_read": 0.1,+ "tiers": [{"input": 2, "output": 4, "cache_read": 0.2, "tier": {"type": "context", "size": 1_000}}],+ })+ assert row_cost(+ {+ "input_tokens": 12_000,+ "cached_input_tokens": 4_000,+ "cache_write_input_tokens": 7_000,+ "cache_write_30m_input_tokens": 3_000,+ "cache_write_12h_input_tokens": 4_000,+ "context_tier": 1_000,+ "output_tokens": 0,+ },+ tiered,+ ).api_cost_usd == pytest.approx(0.0303)+++def test_openai_usage_witnesses_missing_evidence_and_deduplicates_stream_frames():+ """Missing totals/breakdowns stay lower-bound evidence; repeated cumulative frames do not double count."""++ complete = {+ "input_tokens": 12_000,+ "input_tokens_details": {+ "cached_tokens": 4_000,+ "cache_write_tokens": 7_000,+ "cache_write_tokens_details": {"ttl_30m_tokens": 3_000, "ttl_12h_tokens": 4_000},+ },+ "output_tokens": 0,+ }+ duplicated = extract_protocol_usage("openai_responses", {"usage": complete, "response": {"usage": complete}})+ assert duplicated == extract_protocol_usage("openai_responses", {"usage": complete})++ missing_total = extract_protocol_usage(+ "openai_responses",+ {"usage": {"input_tokens": 12_000, "input_tokens_details": {"cached_tokens": 4_000, "cache_write_tokens_details": complete["input_tokens_details"]["cache_write_tokens_details"]}, "output_tokens": 0}},+ )+ assert missing_total is not None+ assert missing_total.cache_write_ttl_uncaptured_reports == 1+ assert missing_total.cache_write_input_tokens == 7_000++ missing_breakdown = extract_protocol_usage(+ "openai_responses",+ {"usage": {"input_tokens": 12_000, "input_tokens_details": {"cached_tokens": 4_000, "cache_write_tokens": 7_000}, "output_tokens": 0}},+ )+ assert missing_breakdown is not None+ assert missing_breakdown.cache_write_input_tokens == 7_000+ assert missing_breakdown.cache_write_ttl_uncaptured_reports == 1+ assert row_cost(+ {+ "requests": 1,+ "token_reports": 1,+ "input_tokens": 12_000,+ "cached_input_tokens": 4_000,+ "cache_write_input_tokens": 7_000,+ "cache_write_ttl_uncaptured_reports": 1,+ "output_tokens": 0,+ },+ _table().price("gpt-5.5"),+ ).api_cost_lower_bound is True++ zero = extract_protocol_usage(+ "openai_responses",+ {"usage": {"input_tokens": 0, "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0, "cache_write_tokens_details": {"ttl_30m_tokens": 0, "ttl_12h_tokens": 0}}, "output_tokens": 0}},+ )+ assert zero == ProtocolUsageReport.of(input_tokens=0, cached_input_tokens=0, output_tokens=0)+++def test_cache_write_subsets_and_folded_incomplete_reports_are_exact():+ """Disjoint bounded subsets and one incomplete witness remain exact in either fold order."""++ invalid = ProtocolUsageReport.of(+ input_tokens=100,+ cached_input_tokens=10,+ output_tokens=0,+ cache_write_input_tokens=60,+ cache_write_1h_input_tokens=0,+ cache_write_30m_input_tokens=40,+ cache_write_12h_input_tokens=30,+ )+ assert invalid.cache_write_1h_input_tokens + invalid.cache_write_30m_input_tokens + invalid.cache_write_12h_input_tokens <= invalid.cache_write_input_tokens+ assert invalid.cache_write_input_tokens <= invalid.input_tokens - invalid.cached_input_tokens+ assert invalid.cache_write_ttl_uncaptured_reports == 1+ invalid_with_witness = ProtocolUsageReport.of(+ input_tokens=100,+ cached_input_tokens=10,+ output_tokens=0,+ cache_write_input_tokens=60,+ cache_write_1h_input_tokens=0,+ cache_write_30m_input_tokens=40,+ cache_write_12h_input_tokens=30,+ cache_write_ttl_uncaptured_reports=1,+ )+ assert invalid_with_witness == invalid+ extracted_invalid = extract_protocol_usage(+ "openai_responses",+ {"usage": {+ "input_tokens": 100,+ "input_tokens_details": {+ "cached_tokens": 10,+ "cache_write_tokens": 60,+ "cache_write_tokens_details": {"ttl_30m_tokens": 40, "ttl_12h_tokens": 30},+ },+ "output_tokens": 0,+ }},+ )+ assert extracted_invalid == invalid++ now = datetime(2026, 10, 26, 12, 0, tzinfo=timezone.utc)+ complete = ProtocolUsageReport.of(+ input_tokens=100, cached_input_tokens=10, output_tokens=1,+ cache_write_input_tokens=80, cache_write_30m_input_tokens=30, cache_write_12h_input_tokens=50,+ )+ incomplete = invalid+ calls = [+ UsageCall("src_openai", "gpt-5.6-oracle", complete, now),+ UsageCall("src_openai", "gpt-5.6-oracle", incomplete, now),+ UsageCall("src_openai", "gpt-5.6-oracle", complete, now),+ ]+ forward = calls[0].folded_with(calls[1]).folded_with(calls[2])+ reverse = calls[2].folded_with(calls[1]).folded_with(calls[0])+ assert forward.usage == reverse.usage+ assert forward.usage is not None+ assert forward.usage.cache_write_ttl_uncaptured_reports == 1+ assert forward.usage.cache_write_30m_input_tokens == 100+def test_priced_usage_with_unknown_parts_is_a_floor():"""MH-PRICE-005: Requests without a token report, or tokens with no price, make the priced figure a lower bound."""@@ -672,13 +855,18 @@ def test_model_price_reads_context_tiers_by_the_flat_price_rules():rates = {"input": 2, "output": 8}# A missing tier member falls back as the flat price's does, to the tier's own input.- tier_rates = ModelPrice(input=2, output=8, cache_read=2, cache_write=2, cache_write_1h=4)+ tier_rates = ModelPrice(+ input=2, output=8, cache_read=2, cache_write=2, cache_write_1h=4, cache_write_30m=2.5, cache_write_12h=5+ )assert model_price({"input": 1, "output": 4, "tiers": [{**rates, "tier": _context(32_000)}]}).context_tiers == ((32_000, tier_rates),)assert model_price(TIERED_CATALOG["openai"]["models"]["gpt-6-astra"]["cost"]).context_tiers == ((272_000,- ModelPrice(input=20, output=75, cache_read=2, cache_write=25, cache_write_1h=40, charges_cache_writes=True),+ ModelPrice(+ input=20, output=75, cache_read=2, cache_write=25, cache_write_1h=40,+ cache_write_30m=25, cache_write_12h=50, charges_cache_writes=True,+ ),),)assert [size for size, _ in model_price(TIERED_CATALOG["openai"]["models"]["gpt-6-nova"]["cost"]).context_tiers] == [32_000, 128_000,@@ -917,6 +1105,26 @@ def test_a_hosted_response_is_priced_by_the_one_pricing_owner(billing, reported,assert result[0] == expected[0] and result[1] == pytest.approx(expected[1])+def test_a_hosted_response_with_incomplete_cache_write_lifetime_is_unpriced() -> None:+ from core.handlers.model_hub.pricing import hosted_response_cost++ result = hosted_response_cost(+ billing="metered",+ reported_usd=None,+ model_price=_table().price("gpt-5.5"),+ usage=ProtocolUsageReport.of(+ input_tokens=1000,+ cached_input_tokens=0,+ output_tokens=0,+ cache_write_input_tokens=600,+ cache_write_ttl_uncaptured_reports=1,+ ),+ tool_prices={},+ counts={},+ )+ assert result is None++def test_a_price_table_parses_every_price_when_built_and_none_on_lookup(monkeypatch):"""MH-PRICE-016: building the table (never on the loop) parses every price, so a lookup on the loop parses none."""from core.handlers.model_hub import pricingdiff --git a/tests/test_model_hub_routing_modes.py b/tests/test_model_hub_routing_modes.pyindex 14175f3d1..5333e2961 100644--- a/tests/test_model_hub_routing_modes.py+++ b/tests/test_model_hub_routing_modes.py@@ -17,7 +17,11 @@ from config.v2_config import (ModelHubSourceStateConfig,)from core.handlers.model_hub.adapter import RawCallOutcome, RawOutcomeKind, SourceBinding-from core.handlers.model_hub.resolver import effective_model_route, resolve_model_hub_turn+from core.handlers.model_hub.resolver import (+ effective_model_route,+ resolve_model_hub_turn,+ validate_cache_ttl_override,+)from core.handlers.model_hub.service import ModelHubErrorfrom scripts.check_model_hub_authorities import AuthorityInput, _typescript_string_unionfrom tests.test_model_hub_resolution import _service, _source@@ -41,7 +45,67 @@ def _pairs(plan):return [(hop.source_id, hop.model_id) for hop in plan.hops]-def test_sparse_matching_tier_excludes_speculation_and_survives_health_changes():+def test_prompt_cache_override_is_route_wide_and_openai_wire_eligible():+ source = _source("src_openai001", ("gpt-6-astra",), vendor="openai")+ config = ModelHubConfig(sources=[source])+ agent = config.agents["vibey"]+ agent.mode = "hub"+ agent.models = [ModelHubBackendModelConfig(id="gpt-6-astra")]+ agent.sources.order = [source.id]+ route = ModelHubRouteConfig(+ hops=(ModelHubRouteHopConfig(source.id, "gpt-6-astra"),),+ cache_ttl="30m",+ )+ agent.routes["gpt-6-astra"] = route++ validate_cache_ttl_override(config, "vibey", route)+ resolution = resolve_model_hub_turn(config, "vibey", "gpt-6-astra")+ assert resolution.cache_ttl == "30m"+ assert resolution.cache_ttl_wire is True++ route = ModelHubRouteConfig(+ hops=(ModelHubRouteHopConfig(source.id, "gpt-6-astra"),),+ cache_ttl="12h",+ )+ agent.routes["gpt-6-astra"] = route+ validate_cache_ttl_override(config, "vibey", route)+ resolution = resolve_model_hub_turn(config, "vibey", "gpt-6-astra")+ assert resolution.cache_ttl == "12h"+ assert resolution.cache_ttl_wire is True+ route = ModelHubRouteConfig(+ hops=(ModelHubRouteHopConfig(source.id, "gpt-6-astra"),),+ cache_ttl="30m",+ )+ agent.routes["gpt-6-astra"] = route+ source.base_url = "https://relay.example.test/v1"+ validate_cache_ttl_override(config, "vibey", route)+ resolution = resolve_model_hub_turn(config, "vibey", "gpt-6-astra")+ assert resolution.cache_ttl == "30m"+ assert resolution.cache_ttl_wire is False+++def test_prompt_cache_override_rejects_unsupported_official_values():+ source = _source("src_openai001", ("gpt-6-astra",), vendor="openai")+ config = ModelHubConfig(sources=[source])+ route = ModelHubRouteConfig(+ hops=(ModelHubRouteHopConfig(source.id, "gpt-6-astra"),),+ cache_ttl="1h",+ )+ with pytest.raises(ValueError, match="30m or 12h"):+ validate_cache_ttl_override(config, "vibey", route)+++def test_prompt_cache_override_is_rejected_for_non_vibey_routes():+ source = _source("src_openai001", ("gpt-6-astra",), vendor="openai")+ config = ModelHubConfig(sources=[source])+ route = ModelHubRouteConfig(+ hops=(ModelHubRouteHopConfig(source.id, "gpt-6-astra"),),+ cache_ttl="30m",+ )+ with pytest.raises(ValueError, match="only for Vibey"):+ validate_cache_ttl_override(config, "claude", route)++absent = _source("src_absent001", ())known = _source("src_known001")config = _sparse_config(absent, known)diff --git a/tests/test_model_hub_service_usage.py b/tests/test_model_hub_service_usage.pyindex ae5dde6b3..a73cd08c5 100644--- a/tests/test_model_hub_service_usage.py+++ b/tests/test_model_hub_service_usage.py@@ -50,7 +50,10 @@ MODEL_COUNTERS = {"output_tokens","cache_write_input_tokens","cache_write_1h_input_tokens",+ "cache_write_30m_input_tokens",+ "cache_write_12h_input_tokens","cache_write_uncaptured_reports",+ "cache_write_ttl_uncaptured_reports",}diff --git a/tests/test_model_hub_usage.py b/tests/test_model_hub_usage.pyindex d3f60201c..ea125a4bd 100644--- a/tests/test_model_hub_usage.py+++ b/tests/test_model_hub_usage.py@@ -70,7 +70,10 @@ def _as_released(counts: dict) -> dict:**counts,"cache_write_input_tokens": 0,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": counts["token_reports"],+ "cache_write_ttl_uncaptured_reports": 0,}@@ -637,7 +640,10 @@ def test_modern_hourly_report_is_dense_and_keeps_source_model_identity("output_tokens": 10,"cache_write_input_tokens": 0,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 0,+ "cache_write_ttl_uncaptured_reports": 0,}measured = {(row["source_id"], row["model_id"]): row@@ -3308,7 +3314,10 @@ def test_a_persisted_report_count_above_its_requests_is_repaired_on_read(# uncaptured cache-write evidence."cache_write_input_tokens": 0,"cache_write_1h_input_tokens": 0,+ "cache_write_30m_input_tokens": 0,+ "cache_write_12h_input_tokens": 0,"cache_write_uncaptured_reports": 3,+ "cache_write_ttl_uncaptured_reports": 0,}diff --git a/tests/test_vibey_agent.py b/tests/test_vibey_agent.pyindex c2d81350a..1638de014 100644--- a/tests/test_vibey_agent.py+++ b/tests/test_vibey_agent.py@@ -4502,6 +4502,22 @@ def test_a_hop_with_an_invalid_hosted_tool_entry_is_refused(hosted_tools) -> Nonselection_from_hop(hop)[email protected]("cache_ttl", ["30m", "12h"])+def test_a_route_cache_ttl_reaches_vibey_selection_endpoint(cache_ttl: str) -> None:+ from modules.agents.vibey.models import selection_from_hop++ hop = ModelHubLaunch(+ backend="vibey", channel="hub", requested_model="gpt-6-astra", target_model="gpt-6-astra",+ runtime_model="gpt-6-astra", source_id="src_openai001", source_identity="sha256:openai-identity",+ gateway_base_url="http://hub.invalid/vibey", gateway_token="hub-token",+ protocol="openai_responses", provider="openai", cache_ttl=cache_ttl, cache_ttl_wire=True,+ ).to_hop_resolution()++ endpoint = selection_from_hop(hop).endpoint+ assert endpoint.cache_ttl == cache_ttl+ assert endpoint.cache_ttl_wire is True++@pytest.mark.parametrize("refused", [True, False], ids=["refused-by-its-source", "never-offered-natively"])async def test_a_proxied_search_names_the_source_that_refused_it(refused) -> None:"""MH-HOSTED-VIBEY-004 (vibey-hosted-tools.md §3.5): a search call runs as its function either because the turn'sdiff --git a/ui/src/components/settings/models/RouteChainDialog.tsx b/ui/src/components/settings/models/RouteChainDialog.tsxindex b99f631d5..68d645cd5 100644--- a/ui/src/components/settings/models/RouteChainDialog.tsx+++ b/ui/src/components/settings/models/RouteChainDialog.tsx@@ -17,12 +17,14 @@ import {import { useTranslation } from "react-i18next";import { Button } from "@/components/ui/button";+import { Select } from "@/components/ui/select";import { ResponsiveMenu } from "@/components/ui/responsive-menu";import { SegmentedRadio } from "@/components/ui/segmented";import { cn } from "@/lib/utils";import { getBackendUiMeta } from "@/lib/agentBackends";import { useIsMobile } from "@/lib/useIsMobile";import { GuardDialog } from "./GuardDialog";+import { Field } from "./dialogFields";import { GuardImpact, type GuardPlan } from "./GuardImpact";import { confirmGuardPlan, sendAgreed, unansweredRefusal } from "./guardedWrite";import { RouteCandidatePopover } from "./RouteCandidatePopover";@@ -52,6 +54,7 @@ import type {Source,ManualRouteOverride,AgentChain,+ CacheTtl,} from "./types";const sourceName = (sources: Source[], sourceId: string): string =>@@ -129,17 +132,20 @@ export const RouteChainDialog: React.FC<{const [phase, setPhase] = React.useState<Phase>("loading");const [origin, setOrigin] = React.useState<RouteHop[]>([]);const [savedOverride, setSavedOverride] = React.useState<ManualRouteOverride | null>(null);+ const [cacheTtlDraft, setCacheTtlDraft] = React.useState<CacheTtl | null>(null);// This is draft routing intent, not whether the rows can be edited.const [manualDraft, setManualDraft] = React.useState(false);const [preview, setPreview] = React.useState<AgentChain | null>(null);const [previewPending, setPreviewPending] = React.useState(false);const [previewFailed, setPreviewFailed] = React.useState(false);+ const [saveErrorCode, setSaveErrorCode] = React.useState<string | null>(null);const previewGeneration = React.useRef(0);- const restoreUndo = React.useRef<{ hops: RouteHop[]; manual: boolean } | null>(null);+ const restoreUndo = React.useRef<{ hops: RouteHop[]; manual: boolean; cacheTtl: CacheTtl | null } | null>(null);const grabIntent = React.useRef<{manual: boolean;+ cacheTtl: CacheTtl | null;preview: AgentChain | null;- undo: { hops: RouteHop[]; manual: boolean } | null;+ undo: { hops: RouteHop[]; manual: boolean; cacheTtl: CacheTtl | null } | null;} | null>(null);const submittedOverride = React.useRef<ManualRouteOverride | null>(null);const interactionRef = React.useRef(createRouteChainInteraction());@@ -200,10 +206,11 @@ export const RouteChainDialog: React.FC<{const previous = interactionRef.current;const next = advanceRouteChainInteraction(previous, action);if (action.type === "begin-grab") {- grabIntent.current = { manual: manualDraft, preview, undo: restoreUndo.current };+ grabIntent.current = { manual: manualDraft, cacheTtl: cacheTtlDraft, preview, undo: restoreUndo.current };}if (action.type === "cancel-grab" && previous.grab && grabIntent.current) {setManualDraft(grabIntent.current.manual);+ setCacheTtlDraft(grabIntent.current.cacheTtl);setPreview(grabIntent.current.preview);restoreUndo.current = grabIntent.current.undo;} else if (action.type !== "reset" && !sameRouteDraft(previous.draft, next.draft)) {@@ -220,7 +227,7 @@ export const RouteChainDialog: React.FC<{setInteraction(next);return next;},- [manualDraft, preview],+ [cacheTtlDraft, manualDraft, preview],);const addCandidates = agent ? routeCandidates(agent, sources, draft) : [];const targetSources = agent ? eligibleSources(sources, agent) : [];@@ -232,7 +239,9 @@ export const RouteChainDialog: React.FC<{: { invalidIndexes: [], valid: false };const restoring = restoreUndo.current !== null;const unresolvedPreview = restoring && preview === null;- const dirty = manualDraft ? savedOverride === null || !sameRouteDraft(savedOverride.hops, draft) : savedOverride !== null;+ const dirty = manualDraft+ ? savedOverride === null || !sameManualOverride(savedOverride, { hops: draft, cache_ttl: cacheTtlDraft })+ : savedOverride !== null;const canDiscardDraft = (phase === "ready" || phase === "rejected") && (dirty || restoring);// A handoff leaves this dialog, so it is offered only on a settled, unedited// route: mid-write phases own an exchange the user must finish, and an unsaved@@ -290,6 +299,7 @@ export const RouteChainDialog: React.FC<{}));setChain(next);setSavedOverride(next.manual_override);+ setCacheTtlDraft(next.manual_override?.cache_ttl ?? null);setManualDraft(next.manual_override !== null);setPreview(null);setPreviewFailed(false);@@ -492,10 +502,12 @@ export const RouteChainDialog: React.FC<{previewGeneration.current += 1;setChain(nextReport.chain);setSavedOverride(nextReport.chain.manual_override);+ setCacheTtlDraft(nextReport.chain.manual_override?.cache_ttl ?? null);setManualDraft(nextReport.chain.manual_override !== null);setPreview(null);setPreviewPending(false);setPreviewFailed(false);+ setSaveErrorCode(null);restoreUndo.current = null;setGuard(null);setOrigin(committedHops);@@ -514,8 +526,12 @@ export const RouteChainDialog: React.FC<{...hop,}));setSubmitted(hops);- if (!confirmation) submittedOverride.current = manualDraft ? { hops } : null;+ const submittedManualOverride = manualDraft+ ? { hops, ...(cacheTtlDraft === null ? {} : { cache_ttl: cacheTtlDraft }) }+ : null;+ if (!confirmation) submittedOverride.current = submittedManualOverride;setSubmittedStage(confirmation ? "confirmed" : "initial");+ setSaveErrorCode(null);setPhase("saving");// A confirmed save keeps its question mounted, busy, until the answer lands;// an initial one shows the progress status in the dialog itself.@@ -525,7 +541,7 @@ export const RouteChainDialog: React.FC<{const guardFields = plan ? confirmGuardPlan(plan) : undefined;return submittedOverride.current === null? modelsApi.restoreAgentChain(agent.backend, modelId, guardFields)- : modelsApi.putAgentChain(agent.backend, modelId, { hops, ...guardFields });+ : modelsApi.putAgentChain(agent.backend, modelId, { ...submittedManualOverride!, ...guardFields });});beginCommitted({@@ -563,6 +579,12 @@ export const RouteChainDialog: React.FC<{return;}setGuard(null);+ setSaveErrorCode(failure?.code ?? null);+ if (failure?.code === "cache_ttl_unsupported") {+ setPhase("ready");+ focusAfterRender(retryButtonRef);+ return;+ }const nextPhase = failure?.serverNamed ? "rejected" : "unknown";setPhase(nextPhase);focusAfterRender(retryButtonRef);@@ -725,9 +747,10 @@ export const RouteChainDialog: React.FC<{const token = ++previewGeneration.current;// Record intent before reading: failure must not leave a saveable empty Manual draft.if (restoreUndo.current === null) {- restoreUndo.current = { hops: draft.map((hop) => ({ ...hop })), manual: manualDraft };+ restoreUndo.current = { hops: draft.map((hop) => ({ ...hop })), manual: manualDraft, cacheTtl: cacheTtlDraft };}setManualDraft(false);+ setCacheTtlDraft(null);setPreview(null);setPreviewPending(true);setPreviewFailed(false);@@ -744,7 +767,7 @@ export const RouteChainDialog: React.FC<{} finally {if (token === previewGeneration.current) setPreviewPending(false);}- }, [advanceInteraction, agent, draft, manualDraft, modelId, phase, previewPending]);+ }, [advanceInteraction, agent, cacheTtlDraft, draft, manualDraft, modelId, phase, previewPending]);const wasCovered = React.useRef(covered);React.useEffect(() => {const leaving = !wasCovered.current && covered;@@ -766,7 +789,9 @@ export const RouteChainDialog: React.FC<{setPreview(null);setPreviewPending(false);setPreviewFailed(false);- setManualDraft(restoreUndo.current?.manual ?? savedOverride !== null);+ const restored = restoreUndo.current;+ setManualDraft(restored?.manual ?? savedOverride !== null);+ setCacheTtlDraft(restored ? restored.cacheTtl : savedOverride?.cache_ttl ?? null);advanceInteraction({ type: 'reset', draft: restoreUndo.current?.hops ?? origin });restoreUndo.current = null;announce('settings.models.routing.undoDone');@@ -780,6 +805,7 @@ export const RouteChainDialog: React.FC<{setPreviewPending(false);setPreviewFailed(false);setManualDraft(false);+ setCacheTtlDraft(null);advanceInteraction({ type: 'reset', draft: origin });setSelectorEpoch((current) => current + 1);};@@ -793,7 +819,10 @@ export const RouteChainDialog: React.FC<{if (manualDraft) return;// Returning from a pending restore brings back the route that was left.if (restoreUndo.current) undoRestore();- else setManualDraft(true);+ else {+ setManualDraft(true);+ setCacheTtlDraft(null);+ }} else if (manualDraft) {followDefaults();focusAfterFollow();@@ -1075,7 +1104,9 @@ export const RouteChainDialog: React.FC<{</div>) : phase === "rejected" ? (<div className="model-hub-route-body flex flex-1 flex-col items-center justify-center gap-3 text-muted">- <p>{t("settings.models.routeDialog.fail.save")}</p>+ <p>{saveErrorCode === "cache_ttl_unsupported"+ ? t("errors.cache_ttl_unsupported")+ : t("settings.models.routeDialog.fail.save")}</p><Buttonref={retryButtonRef}type="button"@@ -1125,6 +1156,36 @@ export const RouteChainDialog: React.FC<{<p className="model-hub-route-mode-copy text-muted">{t(manualDraft ? "settings.models.routing.manualHint" : "settings.models.routing.follows", { backend })}</p>+ {agent?.backend === "vibey" && manualDraft && (+ <Field+ className="mt-3 text-sm"+ label={t("settings.models.routing.cacheTtl.label")}+ hint={t("settings.models.routing.cacheTtl.help")}+ >+ {(id) => (+ <>+ <Select+ id={id}+ wrapperClassName="w-fit"+ value={cacheTtlDraft ?? ""}+ onChange={(event) => setCacheTtlDraft((event.target.value || null) as CacheTtl | null)}+ disabled={phase !== "ready" || previewPending}+ >+ <option value="">{t("settings.models.routing.cacheTtl.default")}</option>+ <option value="5m">{t("settings.models.routing.cacheTtl.5m")}</option>+ <option value="30m">{t("settings.models.routing.cacheTtl.30m")}</option>+ <option value="1h">{t("settings.models.routing.cacheTtl.1h")}</option>+ <option value="12h">{t("settings.models.routing.cacheTtl.12h")}</option>+ </Select>+ {saveErrorCode === "cache_ttl_unsupported" && (+ <span role="alert" className="text-xs text-danger">+ {t("errors.cache_ttl_unsupported")}+ </span>+ )}+ </>+ )}+ </Field>+ )}</div>{!unresolvedPreview && <div inert={previewPending} className="model-hub-route-list flex flex-col">{draft.length ? (diff --git a/ui/src/components/settings/models/routeChainDraft.test.ts b/ui/src/components/settings/models/routeChainDraft.test.tsindex a4884ae3c..733cbaae8 100644--- a/ui/src/components/settings/models/routeChainDraft.test.ts+++ b/ui/src/components/settings/models/routeChainDraft.test.ts@@ -52,7 +52,8 @@ describe("routeChainDraft", () => {expect(sameManualOverride(null, { hops: [] })).toBe(true);expect(sameManualOverride({ hops: [] }, null)).toBe(true);const hops = [{ source_id: 'src_a', model_id: 'model-a' }];- expect(sameManualOverride(null, { hops })).toBe(false);+ expect(sameManualOverride({ hops }, { hops, cache_ttl: "1h" })).toBe(false);+ expect(sameManualOverride({ hops, cache_ttl: "1h" }, { hops, cache_ttl: "1h" })).toBe(true);expect(routeChainMatchesAttempt({ backend: 'claude', model_id: 'opus-5', manual_override: null } as Parameters<typeof routeChainMatchesAttempt>[0], {backend: 'claude', modelId: 'opus-5', submitted: [], manual_override: { hops: [] },})).toBe(true);diff --git a/ui/src/components/settings/models/routeChainDraft.ts b/ui/src/components/settings/models/routeChainDraft.tsindex 19f3b2861..f7a1261b4 100644--- a/ui/src/components/settings/models/routeChainDraft.ts+++ b/ui/src/components/settings/models/routeChainDraft.ts@@ -114,7 +114,7 @@ export const sameRouteDraft = (left: RouteHop[], right: RouteHop[]): boolean =>left.every((hop, index) => identity(hop) === identity(right[index]));export const sameManualOverride = (left: ManualRouteOverride | null, right: ManualRouteOverride | null): boolean =>- sameRouteDraft(left?.hops ?? [], right?.hops ?? []);+ sameRouteDraft(left?.hops ?? [], right?.hops ?? []) && (left?.cache_ttl ?? null) === (right?.cache_ttl ?? null);export const routeChainMatchesAttempt = (chain: AgentChain,diff --git a/ui/src/components/settings/models/types.ts b/ui/src/components/settings/models/types.tsindex 9e06390a1..cf482f3c3 100644--- a/ui/src/components/settings/models/types.ts+++ b/ui/src/components/settings/models/types.ts@@ -415,8 +415,10 @@ export type RouteHopRef = RouteHop & {position: number;};+export type CacheTtl = '5m' | '30m' | '1h' | '12h';export type AgentRoute = {hops: RouteHop[];+ cache_ttl?: CacheTtl | null;};export type ManualRouteOverride = AgentRoute;export type RouteOrigin = 'automatic' | 'manual' | 'passthrough' | null;@@ -871,6 +873,12 @@ export type UsageCounters = {cache_write_input_tokens?: number;/** Subset of `cache_write_input_tokens` written with the one-hour lifetime. */cache_write_1h_input_tokens?: number;+ /** OpenAI Responses cache-write tokens written with the 30-minute lifetime. */+ cache_write_30m_input_tokens?: number;+ /** OpenAI Responses cache-write tokens written with the 12-hour lifetime. */+ cache_write_12h_input_tokens?: number;+ /** OpenAI Responses reports whose total or lifetime write breakdown was missing or invalid. */+ cache_write_ttl_uncaptured_reports?: number;/** Token reports that could not carry cache writes (metered before they were* captured, or on a protocol without them). */cache_write_uncaptured_reports?: number;@@ -1401,6 +1409,7 @@ export type AgentSourcesPut = {/** PUT /api/models/agents/<backend>/chain?model=<id> — replaces exact hops. */export type AgentChainPut = {hops: RouteHop[];+ cache_ttl?: CacheTtl | null;force?: boolean;would_remove_hops?: RouteHopRef[];would_interrupt?: SupplyGap[];diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.jsonindex 5ef136db4..ff3f0ce3d 100644--- a/ui/src/i18n/en.json+++ b/ui/src/i18n/en.json@@ -1375,6 +1375,15 @@},"follows": "Follows {{backend}} default routing. Changes to default routing apply here automatically.","manualHint": "Only this model. Changes to default routing do not overwrite these route entries.",+ "cacheTtl": {+ "label": "Conversation cache lifetime",+ "default": "Use built-in estimate",+ "5m": "5 minutes",+ "30m": "30 minutes",+ "1h": "1 hour",+ "12h": "12 hours",+ "help": "This route-wide estimate controls when old tool results are cleared. Official OpenAI Responses GPT-5.6+ uses a 30-minute cache by default; selecting 30 minutes or 12 hours explicitly sends that provider option. The 12-hour mode costs 2.5x the model input rate for writes versus 1.25x for 30 minutes; cached reads keep the model-specific read price. Earlier OpenAI models' policy-dependent prompt_cache_retention is not inferred. Relays do not receive OpenAI-specific cache options."+ },"undoDone": "Previous manual draft restored.","restorePending": "Not saved yet. The saved route is still in use.","preview": {@@ -2841,6 +2850,7 @@"errors": {"avault_authorization_required": "avault needs a one-time macOS Keychain authorization on the Mac running Avibe. Choose Authorize avault, then answer the dialog on that Mac.","invalid_field_name": "Use 1–64 lowercase letters, digits or underscores for field names, starting with a letter.",+ "cache_ttl_unsupported": "That cache lifetime is not supported by this route. Use the built-in estimate or a provider-compatible value.","field_exists": "A field with this name already exists. Choose a different name.","field_not_found": "This field no longer exists. Refresh the secret and choose one of its current fields.","too_many_fields": "A secret can have at most 32 fields, including the default field.",diff --git a/ui/src/i18n/zh.json b/ui/src/i18n/zh.jsonindex 1fcc7482b..a5373da13 100644--- a/ui/src/i18n/zh.json+++ b/ui/src/i18n/zh.json@@ -1375,6 +1375,15 @@},"follows": "跟随 {{backend}} 的默认路由,默认路由调整后自动生效。","manualHint": "仅此模型。默认路由的调整不会覆盖这些路由项。",+ "cacheTtl": {+ "label": "对话缓存时长",+ "default": "使用内置估计",+ "5m": "5 分钟",+ "30m": "30 分钟",+ "1h": "1 小时",+ "12h": "12 小时",+ "help": "这个路由级估计决定何时清理旧工具结果。官方 OpenAI Responses GPT-5.6+ 默认使用 30 分钟缓存;选择 30 分钟或 12 小时会显式发送对应的提供商选项。12 小时写入按模型输入价格的 2.5 倍计费,30 分钟写入为 1.25 倍;缓存读取仍使用模型专属读取价格。较早 OpenAI 模型依赖组织策略的 prompt_cache_retention 不会被自动推断。中继不会收到 OpenAI 专用缓存参数。"+ },"undoDone": "已恢复之前的手动草稿。","restorePending": "尚未保存,当前仍使用已保存的路由。","preview": {@@ -2841,6 +2850,7 @@"errors": {"avault_authorization_required": "avault 需要在运行 Avibe 的 Mac 上完成一次性的 macOS 钥匙串授权。请选择「授权 avault」,然后在那台 Mac 上回应对话框。","invalid_field_name": "字段名须为 1–64 个小写字母、数字或下划线,且以字母开头。",+ "cache_ttl_unsupported": "此路由不支持该缓存时长。请使用内置估计或符合供应商能力的值。","field_exists": "此字段名已存在,请使用其他名称。","field_not_found": "此字段已不存在。请刷新密钥并选择当前字段。","too_many_fields": "每个密钥最多可包含 32 个字段(含默认字段)。",