Skip to content

armgit / avibe

Public Imported from GitHub
0

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

feat(model-hub): pin Vibey requests with hosted content to their Source and hand them back as pin_unavailable (#2557)

Call White7ebd46869af2
diff --git a/core/handlers/model_hub/hosted_admission.py b/core/handlers/model_hub/hosted_admission.py
new file mode 100644
index 000000000..27d4c2d65
--- /dev/null
+++ b/core/handlers/model_hub/hosted_admission.py
@@ -0,0 +1,228 @@
+"""Which hops may receive a Vibey request's hosted-tool content (``vibey-hosted-tools.md`` §3.5).
+
+The gateway never rewrites hosted content; it only decides where a request may
+go. A hop may receive a hosted declaration only with positive ``call``
+evidence for it, and a replayed native payload only with positive ``replay``
+evidence, both taken on the current engine and probe shape. Evidence is read,
+never written here.
+
+Vibey pins a request carrying such content to one Source with
+``x-avibe-pin-source``. A pinned request goes only to that Source, and every
+way it cannot be served there before output becomes ``pin_unavailable``, after
+which Vibey re-renders it in portable form. A pinned request's in-flight
+response (a ``pause_turn`` continuation, or client tool results after server
+tools in the same response) is the provider's own continuation contract, so
+its hosted items need no replay evidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from functools import lru_cache
+from typing import Any, Callable, Final, Mapping, Optional
+
+from config.v2_config import ModelHubSourceConfig
+from vibe.backend_model_catalog import HostedToolSpec, bundled_provider_overlay
+
+from .capability_evidence import HOSTED_TOOL_ASPECTS, CapabilityEvidenceStore, EvidenceFeature
+from .hosted_tools import credential_eligible, untranslated
+
+PIN_SOURCE_HEADER: Final = "x-avibe-pin-source"
+# The served-hop model a continuation was rendered for; without it a pin is the launch's primary hop.
+PIN_MODEL_HEADER: Final = "x-avibe-pin-model"
+PIN_UNAVAILABLE_CODE: Final = "pin_unavailable"
+
+# Responses items that carry a hosted call's native result, by catalog tool.
+_RESPONSES_HOSTED_ITEMS: Final = {"web_search_call": "web_search", "image_generation_call": "image_generation"}
+# xAI runs X search as custom tool calls; their names are the provider's.
+_X_SEARCH_CALLS: Final = frozenset({"x_keyword_search", "x_semantic_search", "x_user_search", "x_thread_fetch"})
+# Client items that may follow an in-flight response.
+_RESPONSES_TOOL_OUTPUTS: Final = frozenset({"function_call_output", "custom_tool_call_output"})
+# Items a Responses model emits. Only these form an in-flight response: anything
+# else ends it, so an unknown item can never exempt a hosted call from evidence.
+_RESPONSES_MODEL_OUTPUTS: Final = frozenset({
+ "reasoning", "function_call", "custom_tool_call", "web_search_call", "image_generation_call",
+ "file_search_call", "computer_call", "code_interpreter_call", "local_shell_call", "mcp_call",
+ "mcp_list_tools", "mcp_approval_request",
+})
+_ANTHROPIC_SERVER_RESULTS: Final = {"web_search_tool_result": "web_search"}
+
+
+SpecLookup = Callable[[str, str, str, str], Optional[HostedToolSpec]]
+
+
+@dataclass(frozen=True)
+class HostedContent:
+ """What a request's hosted content needs from a hop.
+
+ ``calls`` holds each declared (catalog tool, declaration ``type``);
+ ``replays`` the catalog tools whose native items it replays.
+ """
+
+ calls: frozenset[tuple[str, str]] = frozenset()
+ replays: frozenset[str] = frozenset()
+
+ def __bool__(self) -> bool:
+ return bool(self.calls or self.replays)
+
+
+@lru_cache(maxsize=1)
+def _declaration_tools() -> Mapping[str, Mapping[str, str]]:
+ """Protocol -> declaration ``type`` -> catalog tool, across every overlay vendor.
+
+ A declaration is recognized by any vendor's type, not only the hop's, so a
+ tool its own vendor does not offer (``x_search`` to OpenAI) is never sent.
+ """
+
+ tools: dict[str, dict[str, str]] = {}
+ for families in bundled_provider_overlay().values():
+ for family in families:
+ for protocol, specs in family.hosted_tools.items():
+ for tool, spec in specs.items():
+ tools.setdefault(protocol, {})[spec.declaration["type"]] = tool
+ return tools
+
+
+def hosted_content(request: Mapping[str, Any], protocol: str, *, pinned: bool) -> HostedContent:
+ """The hosted declarations and replayed native items in a request body, by tool."""
+
+ declared = _declaration_tools().get(protocol, {})
+ tools = request.get("tools")
+ calls = frozenset(
+ (declared[tool["type"]], tool["type"])
+ for tool in (tools if isinstance(tools, list) else ())
+ if isinstance(tool, Mapping) and isinstance(tool.get("type"), str) and tool["type"] in declared
+ )
+ if protocol == "openai_responses":
+ replays = _responses_replays(request.get("input"), pinned=pinned)
+ elif protocol == "anthropic":
+ replays = _anthropic_replays(request.get("messages"), pinned=pinned)
+ else:
+ replays = frozenset()
+ return HostedContent(calls, replays)
+
+
+def _responses_hosted_tool(item: Any) -> str | None:
+ if not isinstance(item, Mapping):
+ return None
+ kind = item.get("type")
+ if kind == "custom_tool_call" and item.get("name") in _X_SEARCH_CALLS:
+ return "x_search"
+ return _RESPONSES_HOSTED_ITEMS.get(kind) if isinstance(kind, str) else None
+
+
+def _responses_output_item(item: Any) -> bool:
+ if not isinstance(item, Mapping):
+ return False
+ kind = item.get("type")
+ if kind is None or kind == "message":
+ return item.get("role") == "assistant"
+ return kind in _RESPONSES_MODEL_OUTPUTS
+
+
+def _responses_replays(items: Any, *, pinned: bool) -> frozenset[str]:
+ if not isinstance(items, list):
+ return frozenset()
+ end = len(items)
+ if pinned:
+ # The in-flight response is the trailing run of output items, followed
+ # only by the client's tool outputs.
+ while end and isinstance(items[end - 1], Mapping) and items[end - 1].get("type") in _RESPONSES_TOOL_OUTPUTS:
+ end -= 1
+ while end and _responses_output_item(items[end - 1]):
+ end -= 1
+ tools = {tool for item in items[:end] if (tool := _responses_hosted_tool(item)) is not None}
+ # An image call is never replayed verbatim, in flight or not: Vibey has
+ # replaced its result with the path record, so no hop may receive it.
+ tools.update(
+ "image_generation" for item in items[end:] if _responses_hosted_tool(item) == "image_generation"
+ )
+ return frozenset(tools)
+
+
+def _anthropic_hosted_tool(block: Any) -> str | None:
+ if not isinstance(block, Mapping):
+ return None
+ kind = block.get("type")
+ if kind == "server_tool_use":
+ name = block.get("name")
+ return name if name in HOSTED_TOOL_ASPECTS else None
+ return _ANTHROPIC_SERVER_RESULTS.get(kind) if isinstance(kind, str) else None
+
+
+def _only_tool_results(message: Any) -> bool:
+ if not isinstance(message, Mapping):
+ return False
+ content = message.get("content")
+ return (
+ message.get("role") == "user"
+ and isinstance(content, list)
+ and bool(content)
+ and all(isinstance(block, Mapping) and block.get("type") == "tool_result" for block in content)
+ )
+
+
+def _anthropic_replays(messages: Any, *, pinned: bool) -> frozenset[str]:
+ if not isinstance(messages, list):
+ return frozenset()
+ in_flight: int | None = None
+ if pinned:
+ # The in-flight response is the last assistant message, when only the
+ # client's tool results (one message per call) follow it.
+ index = len(messages)
+ while index and _only_tool_results(messages[index - 1]):
+ index -= 1
+ if index and isinstance(messages[index - 1], Mapping) and messages[index - 1].get("role") == "assistant":
+ in_flight = index - 1
+ tools: set[str] = set()
+ for index, message in enumerate(messages):
+ if index == in_flight or not isinstance(message, Mapping) or message.get("role") != "assistant":
+ continue
+ content = message.get("content")
+ for block in content if isinstance(content, list) else ():
+ if (tool := _anthropic_hosted_tool(block)) is not None:
+ tools.add(tool)
+ return frozenset(tools)
+
+
+def admits(
+ content: HostedContent,
+ *,
+ source: ModelHubSourceConfig,
+ model_id: str,
+ spec_for: SpecLookup,
+ evidence: CapabilityEvidenceStore,
+ engine: str,
+ shape: int,
+ now: datetime,
+) -> bool:
+ """Whether this hop offers every piece of hosted content and has current positive evidence for it.
+
+ The overlay must still offer the tool on this hop, with the declaration
+ type the request carries, as native resolution requires. The first lookup
+ may load the evidence file, so call this off the event loop.
+ """
+
+ if not content:
+ return True
+ if not credential_eligible(source) or not untranslated(source):
+ return False
+
+ def offered(tool: str) -> HostedToolSpec | None:
+ return spec_for(source.vendor, source.protocol, model_id, tool)
+
+ def verified(tool: str, aspect: str) -> bool:
+ if aspect not in HOSTED_TOOL_ASPECTS.get(tool, ()):
+ # A generated image is never replayed verbatim, so nothing can admit it.
+ return False
+ view = evidence.view(
+ source, model_id, EvidenceFeature.hosted(tool, aspect), engine=engine, shape=shape, now=now,
+ )
+ return view.status == "verified"
+
+ for tool, kind in content.calls:
+ spec = offered(tool)
+ if spec is None or spec.declaration["type"] != kind or not verified(tool, "call"):
+ return False
+ return all(offered(tool) is not None and verified(tool, "replay") for tool in content.replays)
diff --git a/core/handlers/model_hub/provenance.py b/core/handlers/model_hub/provenance.py
index f3e8dc882..06ac6e28b 100644
--- a/core/handlers/model_hub/provenance.py
+++ b/core/handlers/model_hub/provenance.py
@@ -719,6 +719,9 @@ class TurnTrace:
# readable; explicit user cancellation suppresses live copy as before.
outcome_frozen: Literal["backend_failure", "user_cancellation"] | None = None
recovery_requests: dict[str, dict] = field(default_factory=dict)
+ # The request whose surfaced attempt set ``terminal_error``, and that exact
+ # value: a handed-back request withdraws only its own terminal.
+ terminal_error_by: Optional[tuple[str, dict]] = None
@property
def pending_attempt(self) -> Optional[AttemptIdentity]:
@@ -862,6 +865,33 @@ class GatewayTurnTerminalizer:
) -> None:
self._staged_exit = {**(self._staged_exit or {}), "fail_reason": reason}
+ def pinned_hop(self, source_id: str, model_id: str | None) -> tuple[str, str | None]:
+ """The exact hop an ``x-avibe-pin-source`` request was rendered for, from explicit or immutable data.
+
+ A continuation names its model (``x-avibe-pin-model``: the served-hop
+ model of the response it continues). Otherwise the pin is the launch's
+ primary hop, whose origin this route credential fixes. A pin that is
+ neither has no model and matches no hop. Nothing turn-wide is read: a
+ turn may have concurrent requests.
+ """
+
+ if model_id is None and self.primary_origin is not None and self.primary_origin.source == source_id:
+ model_id = self.primary_origin.model
+ return source_id, model_id
+
+ def hand_back(self) -> None:
+ """End this request without an exit of its own: its caller re-sends the content.
+
+ A pinned Vibey request the gateway cannot serve (``pin_unavailable``)
+ is re-rendered and sent again in the same turn. Attempts it made stay
+ recorded; the turn settles on the request that follows.
+ """
+
+ self._registry.withdraw_terminal_error(self.turn_id, request_id=self._request_id)
+ self._registry.clear_prepared_attempt(self.turn_id, request_id=self._request_id)
+ self._staged_exit = None
+ self._exit_committed = True
+
def engine_down(self, *, local_error_detail: str | None = None) -> None:
self._registry._terminalize_gateway_exit(
self.turn_id,
@@ -2417,6 +2447,21 @@ class TurnCorrelationRegistry:
"upstream_error_code": diagnostic_code,
**detail,
}
+ trace.terminal_error_by = (request_id, trace.terminal_error)
+
+ def withdraw_terminal_error(self, turn_id: Optional[str], *, request_id: str) -> None:
+ """Drop the terminal a handed-back request surfaced; it did not end the turn."""
+
+ if turn_id is None:
+ return
+ with self._lock:
+ trace = self._traces.get(turn_id)
+ if trace is None or trace.outcome_frozen or trace.terminal_error_by is None:
+ return
+ owner, value = trace.terminal_error_by
+ if owner == request_id and trace.terminal_error is value:
+ trace.terminal_error = None
+ trace.terminal_error_by = None
def close_turn_admission(self, turn_id: str, *, settled_by: Optional[str]) -> None:
"""Latch the FSM boundary without discarding already-owned requests."""
diff --git a/core/handlers/model_hub/request.py b/core/handlers/model_hub/request.py
index bd43c94a3..73b88c30a 100644
--- a/core/handlers/model_hub/request.py
+++ b/core/handlers/model_hub/request.py
@@ -33,6 +33,7 @@ class ModelHubRequest(dict[str, Any]):
protocol: str,
headers: Mapping[str, str] | None = None,
primary_origin: HopOrigin | None = None,
+ pinned_hop: tuple[str, str | None] | None = None,
) -> None:
super().__init__(payload)
self.protocol = protocol
@@ -40,6 +41,10 @@ class ModelHubRequest(dict[str, Any]):
# Launch snapshot, not wire JSON. Every retry compares against this
# origin, even when resolution restarts after cooldown/config changes.
self.primary_origin = primary_origin
+ # The one (Source, model) a Vibey request carrying Source-specific hosted
+ # content may be served by: no failover, no recovery wait, no rewrite.
+ # A model of None matches no hop.
+ self.pinned_hop = pinned_hop
_OPAQUE_FIELDS = frozenset({"signature", "thoughtSignature", "thought_signature", "encrypted_content"})
@@ -104,7 +109,7 @@ def without_opaque_history(request: Mapping[str, Any]) -> Mapping[str, Any]:
if isinstance(request, ModelHubRequest):
return ModelHubRequest(
payload, protocol=request.protocol, headers=request.headers,
- primary_origin=request.primary_origin,
+ primary_origin=request.primary_origin, pinned_hop=request.pinned_hop,
)
return payload
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index b18bc9a34..b437d43c1 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -108,8 +108,10 @@ from .events import (
)
from .capability_evidence import CapabilityEvidenceStore, EvidenceFeature, EvidenceRecord, identity_digest
from .errors import ModelDiscoveryError
+from .evidence_rules import LearnedEvidence
from .evidence_rules import learn as learn_from_rejection
from .evidence_rules import wire_effort
+from .hosted_admission import PIN_UNAVAILABLE_CODE, HostedContent, admits, hosted_content
from .hosted_tools import (
HOSTED_PROBE_SHAPE,
HostedToolSettingRefused,
@@ -684,6 +686,18 @@ class _InvocationUnsupported(_InvocationPlanChanged):
self.reason = reason
+def _pinned_hop(request: Any, backend: str) -> tuple[str, str | None] | None:
+ """The exact (Source, model) a Vibey request is pinned to (``x-avibe-pin-source``), if any."""
+
+ return getattr(request, "pinned_hop", None) if backend == "vibey" else None
+
+
+def _pin_unavailable() -> ModelHubError:
+ """The pinned hop cannot serve this request before output (``vibey-hosted-tools.md`` §3.5)."""
+
+ return ModelHubError(PIN_UNAVAILABLE_CODE, status=409)
+
+
def _google_admission_skip_reason(
frontend_protocol: str | None,
source_protocol: str,
@@ -5844,11 +5858,11 @@ class ModelHubService:
async def _learn_capability_evidence(
self, source: ModelHubSourceConfig, model_id: str, request: Any, outcome: RawCallOutcome
- ) -> None:
- """Record the one feature a 400 before output names, through the narrow rules."""
+ ) -> LearnedEvidence | None:
+ """Record the one feature a 400 before output names, through the narrow rules; return it."""
if outcome.rejection is None:
- return
+ return None
learned = learn_from_rejection(
request,
outcome.rejection,
@@ -5858,7 +5872,7 @@ class ModelHubService:
spec_for=hosted_tool_spec,
)
if learned is None:
- return
+ return None
try:
await asyncio.to_thread(
self.capability_evidence.write,
@@ -5879,6 +5893,21 @@ class ModelHubService:
except (OSError, ValueError):
# Evidence is advisory state: losing one record leaves the priors.
logger.warning("Model Hub could not record capability evidence", exc_info=True)
+ return learned
+
+ def _admits_hosted(self, content: HostedContent, source: ModelHubSourceConfig, model_id: str) -> bool:
+ """Whether this hop has current positive evidence for a request's hosted content; off the loop."""
+
+ return admits(
+ content,
+ source=source,
+ model_id=model_id,
+ spec_for=hosted_tool_spec,
+ evidence=self.capability_evidence,
+ engine=self.engine_stamp,
+ shape=HOSTED_PROBE_SHAPE,
+ now=self.now(),
+ )
def hosted_tools_for_hop(self, config: ModelHubConfig, source: ModelHubSourceConfig, model_id: str) -> dict:
"""``HopResolution.hosted_tools`` for a Vibey launch served by this Source and model."""
@@ -8744,10 +8773,12 @@ class ModelHubService:
try:
config = self.store.load()
resolution = self._invocation_resolution(config, backend, requested_model_id, supply_channel)
+ pinned_hop = _pinned_hop(request, backend)
candidates = [
hop for hop in resolution.candidate_hops
if hop.source_id not in excluded_source_ids
and (hop.source_id, hop.model_id) not in (excluded_hops or ())
+ and (pinned_hop is None or (hop.source_id, hop.model_id) == pinned_hop)
]
candidate = next(
(
@@ -8777,7 +8808,9 @@ class ModelHubService:
origin.response_headers()
except ServedHopHeaderTooLarge:
raise ModelHubError("served_hop_too_large", status=422) from None
- if getattr(request, "primary_origin", None) != origin:
+ # A pinned request was rendered for its pinned Source and is
+ # never rewritten; only an unpinned one is stripped here.
+ if pinned_hop is None and getattr(request, "primary_origin", None) != origin:
attempt_request = without_opaque_history(request)
if self._engine_synced:
if recovery_request is not None and recovery_request.expired:
@@ -9068,6 +9101,21 @@ class ModelHubService:
) -> ResolvedInvocation:
if backend not in MODEL_HUB_BACKENDS:
raise ModelHubError("mapping_target_unavailable")
+ pinned_hop = _pinned_hop(request, backend)
+ hosted = (
+ # A walk of the whole history, so off the controller loop.
+ await asyncio.to_thread(
+ hosted_content, request, getattr(request, "protocol", ""), pinned=pinned_hop is not None,
+ )
+ if backend == "vibey"
+ else HostedContent()
+ )
+ if hosted and pinned_hop is None:
+ # Vibey pins every request carrying Source-specific hosted content,
+ # so unpinned content has no correct hop: refuse it before anything runs.
+ raise ModelHubError(
+ "hosted_content_unpinned", status=422, turn_outcome=REQUEST_NONFALLBACK_TURN_OUTCOME,
+ )
engine_prepared = False
# An entirely unsupported Google request must not reconcile the engine
# or custody. Supported hops drain the journal in demand preparation.
@@ -9087,6 +9135,10 @@ class ModelHubService:
)
event_agent = cast(EventAgent, backend)
candidate_hops = list(resolution.candidate_hops)
+ if pinned_hop is not None and all((hop.source_id, hop.model_id) != pinned_hop for hop in candidate_hops):
+ # Cooling down, removed, or no longer this route's hop: refused
+ # before anything is invoked, and never waited out.
+ raise _pin_unavailable()
if not candidate_hops:
projection_config, projection_resolution = config, resolution
if supply_channel is not None:
@@ -9146,6 +9198,7 @@ class ModelHubService:
hop for hop in resolution.candidate_hops
if hop.source_id not in globally_blocked_source_ids
and (hop.source_id, hop.model_id) not in unsupported_hops
+ and (pinned_hop is None or (hop.source_id, hop.model_id) == pinned_hop)
),
None,
)
@@ -9208,6 +9261,12 @@ class ModelHubService:
if self._effort_refused(source, target_model, request):
effort_rejected_sources.append(source.id)
raise _InvocationUnsupported("effort_unsupported")
+ if pinned_hop is not None and getattr(request, "protocol", None) != source.protocol:
+ # Native content is never translated: the pinned hop must speak the request's protocol.
+ raise _pin_unavailable()
+ if hosted and not await asyncio.to_thread(self._admits_hosted, hosted, source, target_model):
+ # The pinned hop has no current positive evidence for this content.
+ raise _pin_unavailable()
await self._prepare_engine_for_demand(already_synced=engine_prepared)
engine_prepared = True
handle, outcome, cancelled = await self._invoke(
@@ -9224,6 +9283,9 @@ class ModelHubService:
recovery_request=recovery_request,
)
except _InvocationUnsupported as skipped:
+ if pinned_hop is not None:
+ # Normal routing would skip this hop; a pinned request cannot.
+ raise _pin_unavailable() from None
unsupported_reason = skipped.reason
unsupported_hops.add((source.id, target_model))
logger.info(
@@ -9261,7 +9323,7 @@ class ModelHubService:
origin=origin,
)
decision = await self._classify_source_outcome(source, outcome)
- await self._learn_capability_evidence(source, target_model, request, outcome)
+ learned = await self._learn_capability_evidence(source, target_model, request, outcome)
if cancelled is not None:
await self._settle_cancelled_attempt(
source=source,
@@ -9325,7 +9387,7 @@ class ModelHubService:
origin=origin,
)
decision = classify_outcome(outcome, refresh_attempted=True)
- await self._learn_capability_evidence(source, target_model, request, outcome)
+ learned = await self._learn_capability_evidence(source, target_model, request, outcome)
if cancelled is not None:
await self._settle_cancelled_attempt(
source=source,
@@ -9379,6 +9441,18 @@ class ModelHubService:
verification_pending=verification_pending,
origin=origin,
)
+ if (
+ pinned_hop is not None
+ and decision.action == "surface"
+ and not outcome.stream_started
+ and learned is not None
+ and learned.feature.kind == "hosted_tool"
+ ):
+ # A narrow hosted-content rule named this refusal and recorded
+ # its evidence: the pinned hop cannot take this content, so the
+ # request goes back to Vibey for its portable form.
+ self.recovery.release(source.id, settlement_generation)
+ raise _pin_unavailable()
if decision.action == "surface":
self.recovery.release(source.id, settlement_generation)
source_transition_persisted: bool | None = None
@@ -9415,6 +9489,19 @@ class ModelHubService:
source_transition_persisted=source_transition_persisted,
),
)
+ if decision.action == "fallback" and pinned_hop is not None:
+ # A failure normal routing would fail over from. The Source's
+ # health is settled as usual; the request goes back to Vibey,
+ # which re-renders it in portable form and sends it unpinned.
+ await self._settle_fallback_source(
+ source,
+ decision,
+ backend=cast(BackendName, backend),
+ model_id=model_id,
+ settlement_generation=settlement_generation,
+ outcome=outcome,
+ )
+ raise _pin_unavailable()
if decision.action == "fallback":
non_retryable_failure |= decision.reason not in RETRY_DELAYS
if recovery_request is not None and decision.reason in RETRY_DELAYS:
@@ -9445,6 +9532,9 @@ class ModelHubService:
turn_outcome=ENGINE_DOWN_TURN_OUTCOME,
local_error_detail=format_os_errno(outcome.os_errno),
)
+ if pinned_hop is not None:
+ # The pinned hop left the route or its recovery window closed.
+ raise _pin_unavailable()
if (
unsupported_reason == "effort_unsupported"
and failed_source is None
diff --git a/core/handlers/model_hub/turn_gateway.py b/core/handlers/model_hub/turn_gateway.py
index a387a579d..72099b571 100644
--- a/core/handlers/model_hub/turn_gateway.py
+++ b/core/handlers/model_hub/turn_gateway.py
@@ -44,6 +44,7 @@ from .provenance import (
project_turn_outcome_copy,
render_turn_outcome_copy,
)
+from .hosted_admission import PIN_MODEL_HEADER, PIN_SOURCE_HEADER, PIN_UNAVAILABLE_CODE
from .request import FORWARDED_CALLER_HEADERS, ModelHubRequest
from .retry import RECOVERY_EXHAUSTED_CODE, RECOVERY_EXHAUSTED_MESSAGE
from .resolver import parse_model_hub_timestamp
@@ -961,7 +962,12 @@ class ModelHubTurnGateway:
execution, terminalizer, status=400, code="invalid_request_error",
turn_outcome=REQUEST_NONFALLBACK_TURN_OUTCOME,
)
- if not isinstance(model_id, str) or not model_id or not isinstance(stream, bool):
+ pin_source_id = request.headers.get(PIN_SOURCE_HEADER) if backend == "vibey" else None
+ pin_model_id = request.headers.get(PIN_MODEL_HEADER) if backend == "vibey" else None
+ if (
+ not isinstance(model_id, str) or not model_id or not isinstance(stream, bool)
+ or pin_source_id == "" or pin_model_id == "" or (pin_model_id is not None and pin_source_id is None)
+ ):
terminalizer.fail("invalid_parameter")
return self._terminal_error_response(
execution,
@@ -1026,6 +1032,9 @@ class ModelHubTurnGateway:
protocol=protocol,
headers=caller_headers,
primary_origin=terminalizer.primary_origin,
+ pinned_hop=(
+ terminalizer.pinned_hop(pin_source_id, pin_model_id) if pin_source_id else None
+ ),
),
stream=stream,
supply_channel="hub",
@@ -1039,6 +1048,15 @@ class ModelHubTurnGateway:
execution.handle = resolved.handle
resources.push_async_callback(resolved.handle.close_stream)
except ModelHubError as exc:
+ if exc.code == PIN_UNAVAILABLE_CODE:
+ # Never shown to the user: Vibey re-renders the request in
+ # portable form and sends it again unpinned in this same turn.
+ terminalizer.hand_back()
+ return web.json_response(
+ {"type": "error", "error": {"type": "model_hub_pin_unavailable", "code": PIN_UNAVAILABLE_CODE}},
+ status=409,
+ headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"},
+ )
turn_outcome = exc.turn_outcome
if turn_outcome is None and exc.code == "engine_down":
turn_outcome = ENGINE_DOWN_TURN_OUTCOME
diff --git a/docs/plans/agent-core-contracts/model-hub-consumer.md b/docs/plans/agent-core-contracts/model-hub-consumer.md
index 681bf0c3e..b2eacb5f3 100644
--- a/docs/plans/agent-core-contracts/model-hub-consumer.md
+++ b/docs/plans/agent-core-contracts/model-hub-consumer.md
@@ -61,6 +61,39 @@ consumer's requirements, and the Model Hub lane lands the change in both places.
- its attempt ends before model output with a failover-class failure;
- its attempt ends before model output with an error that a narrow hosted-content evidence rule names.
- Vibey then renders the same request in portable form and sends it unpinned; it fails over as today.
+ - **The pin names an exact hop.** It is the pinned Source with the model the content was rendered for:
+ - the model in `x-avibe-pin-model`, which a continuation sets to the served-hop `model` of the response it
+ continues;
+ - otherwise the launch's primary hop model, when the pin is the primary Source. The route credential fixes
+ that model.
+ - A pin that is neither matches no hop.
+ - Nothing turn-wide is read, because a turn may have concurrent requests.
+ - **Admission** reads the overlay and the evidence at the current engine and probe shape:
+ - the pinned hop must be a runnable hop of the route;
+ - every hosted declaration in `tools` needs the overlay to still offer that tool on the hop with that
+ declaration `type`, and `call` evidence. A declaration is a tool whose `type` the overlay declares for a
+ catalog tool on this protocol, for any vendor; a function never is one;
+ - every replayed hosted item outside the in-flight response needs the overlay to still offer its tool on the
+ hop, and `replay` evidence. A generated image never has it.
+ - The hosted items are Responses `web_search_call`, `image_generation_call`, and `custom_tool_call` named
+ `x_keyword_search`, `x_semantic_search`, `x_user_search` or `x_thread_fetch`; and Anthropic `server_tool_use`
+ named after a catalog tool, and `web_search_tool_result`.
+ - The **in-flight response** is structural. On Anthropic it is the last assistant message, when the request ends
+ with it or with user messages made only of `tool_result` blocks. On Responses it is the trailing run of model
+ output items (an assistant `message`, `reasoning`, and the known call item types), followed only by
+ `function_call_output` or `custom_tool_call_output` items. Any other item ends the run, so an unknown item
+ never exempts a hosted call from evidence.
+ - A pinned request is forwarded with nothing changed but `model` and `stream`, so Vibey renders all of it, earlier
+ history included, for the pinned Source's origin.
+ - **Unpinned hosted content is refused.** Vibey pins every request carrying Source-specific hosted content:
+ native declarations, replayed native items, and in-flight continuations. An unpinned Vibey request carrying
+ any of it therefore has no correct hop, and the gateway answers 422 `hosted_content_unpinned` before anything
+ runs.
+ - **Native content is never translated.** The pinned hop must speak the request's protocol; otherwise the
+ answer is `pin_unavailable`.
+ - A `pin_unavailable` carries no routing state into the resend. Every failover-class failure that is health
+ evidence settles the Source as normal routing does, so the resend skips it. An unrecognized error frame inside
+ a 2xx is not health evidence, so the resend may try that Source once more.
- Item 6 (the opaque thinking strip) is unchanged and applies only to unpinned requests.
- The served-hop report carries `source`, the serving Source id (item 4, Model Hub contract v12), so that a
hosted block's payload is tagged with the exact Source; two Sources can share an origin. The gateway and the
diff --git a/tests/scenarios/INDEX.yaml b/tests/scenarios/INDEX.yaml
index 659fa1853..3a4e35969 100644
--- a/tests/scenarios/INDEX.yaml
+++ b/tests/scenarios/INDEX.yaml
@@ -60,6 +60,7 @@ capabilities:
- tests/test_model_hub_evidence_rules.py
- tests/test_model_hub_admission.py
- tests/test_model_hub_vibey_consumer.py
+ - tests/test_model_hub_hosted_pinning.py
- tests/test_model_hub_config.py
- tests/test_model_hub_legacy_opencode_migration.py
- tests/test_model_hub_persisted_migration.py
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index 627046634..d2aa9b985 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -5,6 +5,7 @@ capability:
canonical_tests:
- tests/test_model_hub_api.py
- tests/test_model_hub_vibey_consumer.py
+ - tests/test_model_hub_hosted_pinning.py
- tests/test_model_hub_hosted_tools_resolution.py
- tests/test_model_hub_hosted_tools_config.py
- tests/test_model_hub_capability_evidence.py
@@ -260,6 +261,23 @@ scenarios:
- tests/test_vibey_backend_registration.py::test_vibey_agent_runs_its_catalogs_first_model_until_it_has_one
- tests/test_vibey_backend_registration.py::test_a_lost_vibey_model_hand_off_heals_on_the_next_start
- tests/test_controller_im_ready.py::test_runtime_services_start_when_post_update_notification_fails
+ - id: MH-HOSTED-GATEWAY-002
+ name: A pinned Vibey request is served only by its Source and unchanged; every refusal or pre-output failure there is pin_unavailable, and unpinned hosted content is refused before anything runs
+ status: covered
+ kind: contract
+ layer: contract
+ test: tests/test_model_hub_hosted_pinning.py::test_a_pinned_request_is_served_only_by_its_source_or_handed_back
+ related_tests:
+ - tests/test_model_hub_hosted_pinning.py::test_the_portable_resend_fails_over_and_the_turn_settles_on_it
+ - tests/test_model_hub_hosted_pinning.py::test_unpinned_hosted_content_is_refused_before_anything_runs
+ - id: MH-HOSTED-GATEWAY-003
+ name: Hosted declarations are recognized by any vendor's type, and only replayed items outside the in-flight response need replay evidence
+ status: covered
+ kind: contract
+ layer: unit
+ test: tests/test_model_hub_hosted_pinning.py::test_only_items_outside_the_in_flight_response_need_replay_evidence
+ related_tests:
+ - tests/test_model_hub_hosted_pinning.py::test_declarations_are_recognized_by_every_vendors_type
- id: MH-LIMITS-001
name: Provider rows written before any models.dev copy was cached take its limits once one arrives, keeping every limit already set
status: covered
diff --git a/tests/test_model_hub_codex_image_tool.py b/tests/test_model_hub_codex_image_tool.py
index 75fa91f62..a1a7abf96 100644
--- a/tests/test_model_hub_codex_image_tool.py
+++ b/tests/test_model_hub_codex_image_tool.py
@@ -21,6 +21,8 @@ import aiohttp
import pytest
from aiohttp import web
+from core.handlers.model_hub.capability_evidence import EvidenceFeature, EvidenceRecord, identity_digest
+from core.handlers.model_hub.hosted_tools import HOSTED_PROBE_SHAPE, engine_stamp
from core.handlers.model_hub.turn_gateway import ModelHubTurnGateway
from modules.agents.model_hub import ModelHubRuntimeRouter
from tests.test_model_hub_l3 import _canonicalize_fixed_test_routes, _service, _source
@@ -102,9 +104,11 @@ def _wire(service, tmp_path, root: str, grants: dict[str, dict]) -> EngineStateS
return state
-async def _post(url: str, token: str, body: dict) -> None:
+async def _post(url: str, token: str, body: dict, headers: dict | None = None) -> None:
async with aiohttp.ClientSession() as downstream:
- async with downstream.post(url, json=body, headers={"Authorization": f"Bearer {token}"}) as response:
+ async with downstream.post(
+ url, json=body, headers={"Authorization": f"Bearer {token}", **(headers or {})},
+ ) as response:
assert response.status == 200, await response.text()
await response.read()
@@ -197,8 +201,12 @@ async def test_codex_requests_reach_the_engine_with_the_engines_own_image_tool(
("claude", "messages"), ("opencode", "responses"), ("vibey", "responses"),
])
async def test_other_callers_reach_the_engine_with_exactly_their_declared_tools(tmp_path, backend, path, declared):
- """MH-HOSTED-GATEWAY-001: Claude, OpenCode and Vibey get no image tool they did not declare."""
- configured = _source("src_shared001", "Responses key")
+ """MH-HOSTED-GATEWAY-001: Claude, OpenCode and Vibey get no image tool they did not declare.
+
+ A Vibey request that declares it is a native declaration, so it is pinned to
+ a hop verified for the tool (MH-HOSTED-GATEWAY-002).
+ """
+ configured = _source("src_shared001", "Responses key", model_id="gpt-6-astra" if backend == "vibey" else "shared-model")
tools = [SHELL, DECLARED_IMAGE] if declared else [SHELL]
if backend == "claude":
tools = [{"name": "shell", "input_schema": {"type": "object"}}, *([DECLARED_IMAGE] if declared else [])]
@@ -211,6 +219,19 @@ async def test_other_callers_reach_the_engine_with_exactly_their_declared_tools(
_canonicalize_fixed_test_routes(service)
service.store.requested_models["opencode"] = "shared-model"
_wire(service, tmp_path, root, {})
+ pin = {}
+ if backend == "vibey" and declared:
+ source = service.store.config.sources[0]
+ service.capability_evidence.write(
+ EvidenceRecord(
+ source_id=source.id, model_id="gpt-6-astra",
+ feature=EvidenceFeature.hosted("image_generation", "call"), status="verified", basis="probe",
+ observed_at=service.now(), engine=engine_stamp(), shape=HOSTED_PROBE_SHAPE,
+ source_identity=identity_digest(source),
+ ),
+ live=service.store.config.sources,
+ )
+ pin = {"x-avibe-pin-source": source.id}
gateway = ModelHubTurnGateway(service)
try:
if backend == "vibey":
@@ -224,7 +245,7 @@ async def test_other_callers_reach_the_engine_with_exactly_their_declared_tools(
resolved_model_id="shared-model", source_id=configured.id,
)
url, model = f"{base_url}/v1/{path}", "shared-model"
- await _post(url, token, {"model": model, "stream": True, "tools": tools, "input": INPUT})
+ await _post(url, token, {"model": model, "stream": True, "tools": tools, "input": INPUT}, pin)
finally:
await gateway.close()
assert len(received) == 1
diff --git a/tests/test_model_hub_hosted_pinning.py b/tests/test_model_hub_hosted_pinning.py
new file mode 100644
index 000000000..a96abee40
--- /dev/null
+++ b/tests/test_model_hub_hosted_pinning.py
@@ -0,0 +1,468 @@
+"""MH-HOSTED-GATEWAY-002/003: a hop receives hosted content only with current positive evidence.
+
+A Vibey request carrying a native hosted declaration or a replayed native
+payload is pinned (``x-avibe-pin-source``). The gateway serves it only from that
+Source, unchanged, and answers ``pin_unavailable`` for every way it cannot be
+served there before output, so Vibey can re-render it portably and resend it
+unpinned (``vibey-hosted-tools.md`` §3.5). These cases drive the real gateway and
+resolver against a recording engine adapter, which shows exactly which hop
+received which body.
+"""
+
+from __future__ import annotations
+
+import copy
+import threading
+from dataclasses import replace
+from datetime import timedelta
+
+import aiohttp
+import pytest
+
+from config.v2_config import ModelHubModelConfig, ModelHubRouteConfig, ModelHubRouteHopConfig
+from core.handlers.model_hub import service as service_module
+from core.handlers.model_hub.adapter import RawOutcomeKind, UpstreamRejection
+from core.handlers.model_hub.capability_evidence import EvidenceFeature, EvidenceRecord, identity_digest
+from core.handlers.model_hub.hosted_admission import hosted_content
+from core.handlers.model_hub.hosted_tools import HOSTED_PROBE_SHAPE, engine_stamp
+from core.handlers.model_hub.turn_gateway import ModelHubTurnGateway
+from core.run_settlement import SETTLED_BY_STOPPED, SETTLED_BY_TERMINAL_RESULT
+from modules.agents.model_hub import ModelHubRuntimeRouter
+from tests.test_model_hub_l3 import NOW, InvokeHandle, LiveInvokeHandle, _outcome, _source
+from tests.test_model_hub_vibey_consumer import _validate, _vibey_service
+
+PIN = "x-avibe-pin-source"
+PIN_MODEL = "x-avibe-pin-model"
+PIN_UNAVAILABLE = {"type": "error", "error": {"type": "model_hub_pin_unavailable", "code": "pin_unavailable"}}
+SHELL = {"type": "function", "name": "shell", "parameters": {"type": "object", "properties": {}}}
+PORTABLE_X_SEARCH = {"type": "function", "name": "x_search", "parameters": {"type": "object", "properties": {}}}
+SIGNED_REASONING = {"type": "reasoning", "id": "rs_1", "summary": [], "encrypted_content": "opaque-signed"}
+
+
+def _sources(*, primary_status="standby", primary_model="grok-4.6"):
+ retry_at = (NOW + timedelta(minutes=5)).isoformat() if primary_status == "cooldown" else None
+ primary = _source("src_primary01", "xAI key", vendor="xai", model_id=primary_model,
+ status=primary_status, retry_at=retry_at)
+ fallback = _source("src_fallback01", "OpenAI key", vendor="openai", model_id="gpt-6-astra")
+ return primary, fallback
+
+
+def _verify(service, source, model_id, tool, aspect, *, engine=None):
+ service.capability_evidence.write(
+ EvidenceRecord(
+ source_id=source.id, model_id=model_id, feature=EvidenceFeature.hosted(tool, aspect),
+ status="verified", basis="probe", observed_at=service.now(), engine=engine or engine_stamp(),
+ shape=HOSTED_PROBE_SHAPE, source_identity=identity_digest(source),
+ ),
+ live=service.store.config.sources,
+ )
+
+
+async def _post(hop, body, *, pin=None, model=None):
+ headers = {"Authorization": f'Bearer {hop["token"]}'}
+ if pin is not None:
+ headers[PIN] = pin
+ if model is not None:
+ headers[PIN_MODEL] = model
+ async with aiohttp.ClientSession() as client:
+ async with client.post(f'{hop["base_url"]}/responses', headers=headers, json=body) as response:
+ return response.status, await response.json(content_type=None)
+
+
+def _native(hop, *, history=()):
+ return {
+ "model": hop["runtime_model"], "stream": False,
+ "input": [*history, {"role": "user", "content": "posts from OpenAI this week"}],
+ "tools": [{"type": "x_search"}, SHELL],
+ }
+
+
[email protected](("case", "status", "invoked"), [
+ ("served", 200, ["src_primary01"]),
+ ("source_that_neither_launched_nor_served", 409, []),
+ ("failure_before_output", 409, ["src_primary01"]),
+ ("request_rejected", 400, ["src_primary01"]),
+ ("no_call_evidence", 409, []),
+ ("overlay_no_longer_offers_the_tool", 409, []),
+ ("evidence_from_another_engine", 409, []),
+ ("source_cooling_down", 409, []),
+ ("source_not_on_route", 409, []),
+])
+async def test_a_pinned_request_is_served_only_by_its_source_or_handed_back(
+ tmp_path, monkeypatch, case, status, invoked,
+):
+ """MH-HOSTED-GATEWAY-002: no failover, no recovery wait, no rewrite; refusals precede any invocation."""
+
+ primary, fallback = _sources(
+ primary_status="cooldown" if case == "source_cooling_down" else "standby",
+ # The overlay offers x_search on grok-4 models only; evidence alone cannot admit it elsewhere.
+ primary_model="grok-3-mini" if case == "overlay_no_longer_offers_the_tool" else "grok-4.6",
+ )
+ primary_model = primary.models[0].id
+ outcome = {
+ "failure_before_output": InvokeHandle(_outcome(RawOutcomeKind.HTTP_ERROR, status=429, code="rate_limit_error")),
+ "request_rejected": InvokeHandle(_outcome(
+ RawOutcomeKind.HTTP_ERROR, status=400, code="invalid_request_error", message="Bad field",
+ )),
+ }.get(case, LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=primary.id), (b"{}",)))
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[
+ outcome, LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=fallback.id), (b"{}",)),
+ ])
+ service.recovery.window_seconds = 120
+ if case == "source_that_neither_launched_nor_served":
+ # Evidence is not enough: nothing this turn was rendered for that Source.
+ _verify(service, fallback, "gpt-6-astra", "web_search", "call")
+ elif case != "no_call_evidence":
+ engine = "model-hub-engine-previous" if case == "evidence_from_another_engine" else None
+ _verify(service, primary, primary_model, "x_search", "call", engine=engine)
+ scanning_threads = []
+ scan = service_module.hosted_content
+
+ def recorded(*args, **kwargs):
+ scanning_threads.append(threading.current_thread())
+ return scan(*args, **kwargs)
+
+ monkeypatch.setattr(service_module, "hosted_content", recorded)
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:pin", turn_id="turn-pin")
+ # Vibey renders a pinned request for its pinned hop, so it carries the
+ # hop's own signed history unchanged.
+ body = _native(hop, history=[SIGNED_REASONING])
+ pin = {"source_not_on_route": "src_absent0001", "source_that_neither_launched_nor_served": fallback.id}.get(
+ case, primary.id,
+ )
+ if pin == fallback.id:
+ body["tools"] = [{"type": "web_search"}, SHELL]
+ sent = copy.deepcopy(body)
+ answer_status, answer = await _post(hop, body, pin=pin)
+ finally:
+ await gateway.close()
+ assert answer_status == status
+ assert [entry[0] for entry in service.adapter.invocations] == invoked
+ # Reading the request's whole history never runs on the controller loop.
+ assert scanning_threads and threading.main_thread() not in scanning_threads
+ if status == 409:
+ assert answer == PIN_UNAVAILABLE
+ if invoked:
+ assert service.adapter.requests[0] == sent
+ if case == "failure_before_output":
+ # The failure still settles the Source's health, as normal routing would.
+ assert service.store.config.sources[0].state.status == "cooldown"
+
+
+ "route_now_maps_the_source_to_another_model", "continuation_after_failover", "named_model_on_a_shared_source",
+])
+async def test_a_pin_names_the_exact_hop_it_was_rendered_for(tmp_path, case):
+ """MH-HOSTED-GATEWAY-002: a pin is the (Source, model) the content was rendered for, never just the Source.
+
+ The model is explicit (``x-avibe-pin-model``, the served-hop model a
+ continuation continues) or the launch's immutable primary hop; never what
+ served the turn last, since a turn can have concurrent requests. A pinned
+ request is never stripped, so content for one model must not reach another.
+ """
+
+ primary, fallback = _sources()
+ primary = replace(primary, models=[*primary.models, ModelHubModelConfig(id="grok-4.7", provenance="discovered")])
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[
+ InvokeHandle(_outcome(RawOutcomeKind.HTTP_ERROR, status=429, code="rate_limit_error")),
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=fallback.id), (b"{}",)),
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=fallback.id), (b"{}",)),
+ ] if case == "continuation_after_failover" else [
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=primary.id), (b"{}",)),
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=primary.id), (b"{}",)),
+ ])
+ for model_id in ("grok-4.6", "grok-4.7"):
+ _verify(service, primary, model_id, "x_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:exact", turn_id="turn-exact")
+ if case == "route_now_maps_the_source_to_another_model":
+ # Mid-turn, the alias moves to another model on the pinned Source.
+ service.store.config.agents["vibey"].routes["menu-alias"] = ModelHubRouteConfig((
+ ModelHubRouteHopConfig(primary.id, "grok-4.7"), ModelHubRouteHopConfig(fallback.id, "gpt-6-astra"),
+ ))
+ assert await _post(hop, _native(hop), pin=primary.id) == (409, PIN_UNAVAILABLE)
+ assert service.adapter.invocations == []
+ return
+ if case == "named_model_on_a_shared_source":
+ service.store.config.agents["vibey"].routes["menu-alias"] = ModelHubRouteConfig((
+ ModelHubRouteHopConfig(primary.id, "grok-4.6"), ModelHubRouteHopConfig(primary.id, "grok-4.7"),
+ ))
+ # A continuation of a response grok-4.7 served, then a new native request: each keeps its own hop,
+ # whatever served last.
+ assert (await _post(hop, _native(hop), pin=primary.id, model="grok-4.7"))[0] == 200
+ assert (await _post(hop, _native(hop), pin=primary.id))[0] == 200
+ assert [entry[:2] for entry in service.adapter.invocations] == [
+ (primary.id, "grok-4.7"), (primary.id, "grok-4.6"),
+ ]
+ return
+ # The previous response failed over to the fallback, which paused it; its continuation is pinned there.
+ assert (await _post(hop, {**_native(hop), "tools": [SHELL]}))[0] == 200
+ continuation = {**_native(hop, history=[SIGNED_REASONING, LOCAL_CALL, LOCAL_OUTPUT]), "tools": [SHELL]}
+ # Without the served model, nothing says which hop it was rendered for.
+ assert await _post(hop, continuation, pin=fallback.id) == (409, PIN_UNAVAILABLE)
+ assert (await _post(hop, continuation, pin=fallback.id, model="gpt-6-astra"))[0] == 200
+ finally:
+ await gateway.close()
+ assert [entry[:2] for entry in service.adapter.invocations] == [
+ (primary.id, "grok-4.6"), (fallback.id, "gpt-6-astra"), (fallback.id, "gpt-6-astra"),
+ ]
+ assert service.adapter.requests[2] == continuation
+
+
+async def test_the_portable_resend_fails_over_and_the_turn_settles_on_it(tmp_path):
+ """MH-HOSTED-GATEWAY-002: the handed-back request leaves only its failed attempt in the turn."""
+
+ primary, fallback = _sources()
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[
+ InvokeHandle(_outcome(RawOutcomeKind.HTTP_ERROR, status=429, code="rate_limit_error")),
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=fallback.id), (b"{}",)),
+ ])
+ _verify(service, primary, "grok-4.6", "x_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ turn_id = "turn-resend"
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:resend", turn_id=turn_id)
+ assert await _post(hop, _native(hop), pin=primary.id) == (409, PIN_UNAVAILABLE)
+ portable = {**_native(hop), "tools": [PORTABLE_X_SEARCH, SHELL]}
+ assert (await _post(hop, portable))[0] == 200
+ completion = router.settle_turn(turn_id, settled_by=SETTLED_BY_TERMINAL_RESULT, ts=NOW.isoformat())
+ if completion:
+ await completion
+ finally:
+ await gateway.close()
+ assert [entry[0] for entry in service.adapter.invocations] == [primary.id, fallback.id]
+ record = service.provenance.get(turn_id)
+ _validate("turn-provenance.schema.json", record)
+ assert record["outcome"] == "served"
+ assert record["served"]["source_id"] == fallback.id
+ assert [attempt["source_id"] for attempt in record["failed_attempts"]] == [primary.id]
+ assert record["terminal_error"] is None
+
+
+async def test_an_ambiguous_pinned_failure_is_no_health_evidence_so_the_resend_may_try_it_again(tmp_path):
+ """MH-HOSTED-GATEWAY-002: an unrecognized error frame in a 2xx writes no Source health, pinned or not.
+
+ The handback carries no routing state: a turn's requests may overlap, so
+ nothing turn-wide could tell the resend from another request.
+ """
+
+ primary, fallback = _sources()
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[
+ InvokeHandle(_outcome(RawOutcomeKind.HTTP_ERROR, status=200, code="unrecognized_fixture")),
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=primary.id), (b"{}",)),
+ ])
+ _verify(service, primary, "grok-4.6", "x_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:resend-walk", turn_id="turn-resend-walk")
+ assert await _post(hop, _native(hop), pin=primary.id) == (409, PIN_UNAVAILABLE)
+ assert (await _post(hop, {**_native(hop), "tools": [PORTABLE_X_SEARCH, SHELL]}))[0] == 200
+ finally:
+ await gateway.close()
+ assert [entry[0] for entry in service.adapter.invocations] == [primary.id, primary.id]
+ assert service.store.config.sources[0].state.status == "standby"
+
+
[email protected](("case", "tools", "history", "status", "invoked"), [
+ # Hosted content is Source-specific, so it travels only pinned; unpinned, no hop is right for it.
+ ("native_declaration", [{"type": "web_search"}], [], 422, []),
+ ("replayed_hosted_item", [SHELL], ["WEB_CALL"], 422, []),
+ # Function tools and plain history are never hosted content.
+ ("portable_request", [PORTABLE_X_SEARCH], [], 200, ["src_primary01"]),
+])
+async def test_unpinned_hosted_content_is_refused_before_anything_runs(tmp_path, case, tools, history, status, invoked):
+ """MH-HOSTED-GATEWAY-002: the gateway never chooses a hop for hosted content; Vibey's pin does."""
+
+ primary, fallback = _sources()
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[
+ LiveInvokeHandle(_outcome(RawOutcomeKind.SUCCESS, source_id=primary.id), (b"{}",)),
+ ])
+ # Evidence everywhere does not make unpinned content admissible.
+ _verify(service, primary, "grok-4.6", "web_search", "call")
+ _verify(service, primary, "grok-4.6", "web_search", "replay")
+ _verify(service, fallback, "gpt-6-astra", "web_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:unpinned", turn_id="turn-unpinned")
+ body = {**_native(hop, history=[WEB_CALL, ASSISTANT_TEXT] if history else []), "tools": [*tools, SHELL]}
+ answer_status, answer = await _post(hop, body)
+ finally:
+ await gateway.close()
+ assert answer_status == status
+ assert [entry[0] for entry in service.adapter.invocations] == invoked
+ if status == 422:
+ assert answer["error"]["code"] == "hosted_content_unpinned"
+
+
+async def test_a_handed_back_refusal_does_not_end_the_turn(tmp_path):
+ """MH-HOSTED-GATEWAY-002: the handback withdraws its own surfaced terminal; the resend's outcome decides the turn."""
+
+ primary, _fallback = _sources()
+ refusal = replace(
+ _outcome(RawOutcomeKind.HTTP_ERROR, status=400, code="invalid_request_error"),
+ rejection=UpstreamRejection(status=400, code="invalid_request_error", unsupported_tool_type="x_search"),
+ )
+ service = _vibey_service(tmp_path, [primary], handles=[InvokeHandle(refusal)])
+ _verify(service, primary, "grok-4.6", "x_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ turn_id = "turn-withdraw"
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:withdraw", turn_id=turn_id)
+ assert await _post(hop, _native(hop), pin=primary.id) == (409, PIN_UNAVAILABLE)
+ # The turn ends before any resend (the user stops it): the handed-back
+ # refusal must not stand as the turn's terminal error.
+ completion = router.settle_turn(turn_id, settled_by=SETTLED_BY_STOPPED, ts=NOW.isoformat())
+ if completion:
+ await completion
+ finally:
+ await gateway.close()
+ record = service.provenance.get(turn_id)
+ _validate("turn-provenance.schema.json", record)
+ # Not the handed-back hosted-tool refusal: that request never ended the turn.
+ assert record["terminal_error"] is None
+ assert record["outcome"] != "failed_terminal"
+
+
+async def test_a_pinned_hop_must_speak_the_requests_protocol(tmp_path):
+ """MH-HOSTED-GATEWAY-002: native content is never translated; a pin across protocols is handed back."""
+
+ primary, fallback = _sources()
+ service = _vibey_service(tmp_path, [primary, fallback])
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:protocol", turn_id="turn-protocol")
+ async with aiohttp.ClientSession() as client:
+ async with client.post(
+ f'{hop["base_url"]}/messages',
+ headers={"Authorization": f'Bearer {hop["token"]}', PIN: primary.id},
+ json={"model": hop["runtime_model"], "max_tokens": 64, "messages": [{"role": "user", "content": "q"}]},
+ ) as response:
+ assert (response.status, await response.json()) == (409, PIN_UNAVAILABLE)
+ finally:
+ await gateway.close()
+ assert service.adapter.invocations == []
+
+
+async def test_a_refusal_naming_the_pinned_hosted_content_is_handed_back_and_learned(tmp_path):
+ """MH-HOSTED-GATEWAY-002: case 3, a narrow hosted-content rule (#2551) turns the pinned 400 into a handback."""
+
+ primary, fallback = _sources()
+ refusal = replace(
+ _outcome(RawOutcomeKind.HTTP_ERROR, status=400, code="invalid_request_error",
+ message="Unsupported tool type: x_search"),
+ rejection=UpstreamRejection(status=400, code="invalid_request_error", error_type="invalid_request_error",
+ unsupported_tool_type="x_search"),
+ )
+ service = _vibey_service(tmp_path, [primary, fallback], handles=[InvokeHandle(refusal)])
+ _verify(service, primary, "grok-4.6", "x_search", "call")
+ gateway = ModelHubTurnGateway(service)
+ router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
+ try:
+ hop = await router.resolve_hop("menu-alias", process_scope="vibey:learn", turn_id="turn-learn")
+ assert await _post(hop, _native(hop), pin=primary.id) == (409, PIN_UNAVAILABLE)
+ finally:
+ await gateway.close()
+ assert [entry[0] for entry in service.adapter.invocations] == [primary.id]
+ learned = service.capability_evidence.view(
+ primary, "grok-4.6", EvidenceFeature.hosted("x_search", "call"),
+ engine=engine_stamp(), shape=HOSTED_PROBE_SHAPE, now=service.now(),
+ )
+ assert (learned.status, learned.record.basis) == ("unsupported", "observed")
+
+
+# Responses and Anthropic histories: (case, protocol, history, pinned, the tools needing replay evidence).
+WEB_CALL = {"type": "web_search_call", "id": "ws_1", "status": "completed", "action": {"type": "search", "query": "q"}}
+X_CALL = {"type": "custom_tool_call", "name": "x_keyword_search", "call_id": "xs_1", "input": "{}"}
+IMAGE_CALL = {"type": "image_generation_call", "id": "ig_1", "status": "completed", "result": "path record"}
+LOCAL_CALL = {"type": "function_call", "call_id": "fc_1", "name": "shell", "arguments": "{}"}
+LOCAL_OUTPUT = {"type": "function_call_output", "call_id": "fc_1", "output": "ok"}
+USER = {"role": "user", "content": "next"}
+ASSISTANT_TEXT = {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "answer"}]}
+SERVER_USE = {"type": "server_tool_use", "id": "srvtoolu_1", "name": "web_search", "input": {"query": "q"}}
+SERVER_RESULT = {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_1", "content": []}
+TOOL_USE = {"type": "tool_use", "id": "toolu_1", "name": "shell", "input": {}}
+
+
+def _tool_result(call_id):
+ return {"role": "user", "content": [{"type": "tool_result", "tool_use_id": call_id, "content": "ok"}]}
+
+
+IN_FLIGHT_CASES = [
+ ("responses_cross_turn", "openai_responses", [USER, WEB_CALL, ASSISTANT_TEXT, USER], True, {"web_search"}),
+ ("responses_in_flight", "openai_responses", [USER, WEB_CALL, X_CALL, LOCAL_CALL, LOCAL_OUTPUT], True, set()),
+ ("responses_in_flight_unpinned", "openai_responses", [USER, WEB_CALL, LOCAL_CALL, LOCAL_OUTPUT], False,
+ {"web_search"}),
+ # An earlier model call of the same turn is history, not the in-flight response.
+ ("responses_earlier_step_of_turn", "openai_responses",
+ [USER, WEB_CALL, LOCAL_CALL, LOCAL_OUTPUT, LOCAL_CALL, LOCAL_OUTPUT], True, {"web_search"}),
+ ("responses_steer_after_tools", "openai_responses", [USER, X_CALL, LOCAL_CALL, LOCAL_OUTPUT, USER], True,
+ {"x_search"}),
+ ("responses_image_cross_turn", "openai_responses", [USER, IMAGE_CALL, ASSISTANT_TEXT, USER], True,
+ {"image_generation"}),
+ # An image call is never replayed verbatim, even in flight: its result is Vibey's path record.
+ ("responses_image_in_flight", "openai_responses", [USER, IMAGE_CALL, LOCAL_CALL, LOCAL_OUTPUT], True,
+ {"image_generation"}),
+ # Only known model output forms the in-flight response; an unknown item ends it.
+ ("responses_unknown_client_item_after_hosted_call", "openai_responses",
+ [USER, WEB_CALL, {"type": "computer_call_output", "call_id": "cc_1", "output": {}}], True, {"web_search"}),
+ ("responses_unknown_custom_call", "openai_responses",
+ [USER, {**X_CALL, "name": "local_freeform"}, ASSISTANT_TEXT, USER], True, set()),
+ ("anthropic_pause_turn", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_USE, SERVER_RESULT, SERVER_USE]}], True, set()),
+ ("anthropic_parallel_tool_results", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_USE, SERVER_RESULT, TOOL_USE, {**TOOL_USE, "id": "toolu_2"}]},
+ _tool_result("toolu_1"), _tool_result("toolu_2")], True, set()),
+ ("anthropic_cross_turn", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_USE, SERVER_RESULT]}, USER], True, {"web_search"}),
+ ("anthropic_earlier_message", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_RESULT, TOOL_USE]}, _tool_result("toolu_1"),
+ {"role": "assistant", "content": [{**TOOL_USE, "id": "toolu_2"}]}, _tool_result("toolu_2")], True,
+ {"web_search"}),
+ ("anthropic_non_object_entry", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_USE, SERVER_RESULT]}, "not a message"], True, {"web_search"}),
+ ("anthropic_unpinned", "anthropic",
+ [USER, {"role": "assistant", "content": [SERVER_USE, SERVER_RESULT]}], False, {"web_search"}),
+]
+
+
[email protected](("protocol", "history", "pinned", "replays"), [case[1:] for case in IN_FLIGHT_CASES],
+ ids=[case[0] for case in IN_FLIGHT_CASES])
+def test_only_items_outside_the_in_flight_response_need_replay_evidence(protocol, history, pinned, replays):
+ """MH-HOSTED-GATEWAY-003: the structural in-flight rule agreed with the Vibey request builder."""
+
+ field = "input" if protocol == "openai_responses" else "messages"
+ content = hosted_content({field: history, "tools": [SHELL]}, protocol, pinned=pinned)
+ assert content.replays == frozenset(replays)
+ assert content.calls == frozenset()
+
+
+def test_declarations_are_recognized_by_every_vendors_type():
+ """MH-HOSTED-GATEWAY-003: a declaration counts whichever vendor offers it, never a function."""
+
+ tools = [{"type": "x_search"}, {"type": "web_search"}, {"type": "image_generation", "partial_images": 2},
+ PORTABLE_X_SEARCH, {"type": "web_search_20250305", "name": "web_search"}]
+ assert hosted_content({"tools": tools}, "openai_responses", pinned=True).calls == frozenset(
+ {("x_search", "x_search"), ("web_search", "web_search"), ("image_generation", "image_generation")}
+ )
+ assert hosted_content({"tools": tools}, "anthropic", pinned=True).calls == frozenset(
+ {("web_search", "web_search_20250305")}
+ )
+ assert not hosted_content({"tools": tools}, "openai_chat", pinned=True)
diff --git a/tests/test_model_hub_structure_guards.py b/tests/test_model_hub_structure_guards.py
index bfec5bca5..a425767d2 100644
--- a/tests/test_model_hub_structure_guards.py
+++ b/tests/test_model_hub_structure_guards.py
@@ -1244,6 +1244,10 @@ def test_machine_error_field_access_has_one_extractor() -> None:
if (history := functions.get(name)) is not None
for node in ast.walk(history)
}
+ if path.name == "hosted_admission.py":
+ # Hosted admission discriminates request tools and history items,
+ # never an error envelope; its type reads are exempt too.
+ history_nodes = set(ast.walk(tree))
for node in ast.walk(tree):
if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
continue
diff --git a/vibe/i18n/en.json b/vibe/i18n/en.json
index 3e8d21390..ecd3cfd11 100644
--- a/vibe/i18n/en.json
+++ b/vibe/i18n/en.json
@@ -1092,6 +1092,7 @@
"candidate_suppliers_changed": "The available suppliers changed. Reload the model choices and confirm again.",
"models_dev_unavailable": "models.dev is unavailable. Enter the model metadata manually or retry later.",
"codex_catalog_unavailable": "Codex could not prepare the local Model Hub catalog. Retry this turn.",
+ "hosted_content_unpinned": "This request carries hosted-tool content that is not pinned to the Source it was rendered for, so no Source may receive it.",
"request_too_large": "This request exceeds Avibe's local {limit_mib} MiB request limit. Reduce the images or conversation context and retry.",
"engine_down": "The local model gateway is unavailable.",
"engine_down_streamed": "The local model gateway is unavailable. This turn's output may be incomplete.",
diff --git a/vibe/i18n/zh.json b/vibe/i18n/zh.json
index dfcf2c632..d6f32a5ad 100644
--- a/vibe/i18n/zh.json
+++ b/vibe/i18n/zh.json
@@ -1092,6 +1092,7 @@
"candidate_suppliers_changed": "可用供应商已发生变化,请刷新模型选项后重新确认。",
"models_dev_unavailable": "models.dev 当前不可用,请手动填写模型参数或稍后重试。",
"codex_catalog_unavailable": "Codex 无法准备本地模型网关目录,请重试本回合。",
+ "hosted_content_unpinned": "此请求携带的托管工具内容未固定到其渲染所针对的来源,因此不能发送给任何来源。",
"request_too_large": "请求超过 Avibe 本地网关的 {limit_mib} MiB 大小上限。请减少图片或对话上下文后重试。",
"engine_down": "本地模型网关不可用。",
"engine_down_streamed": "本地模型网关不可用。本回合输出可能不完整。",