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(vibey): parse hosted calls into canonical records and replay them portably (#2561)

Call Whitecec226ca4d0d
diff --git a/core/agent_core/ai/_common.py b/core/agent_core/ai/_common.py
index 521473ea3..1e639faf7 100644
--- a/core/agent_core/ai/_common.py
+++ b/core/agent_core/ai/_common.py
@@ -10,7 +10,7 @@ import inspect
import json
import re
from collections.abc import AsyncIterator, Awaitable, Callable, Hashable, Mapping
-from dataclasses import dataclass, field, replace
+from dataclasses import asdict, dataclass, field, fields, is_dataclass, replace
from typing import Any, TypeVar
from urllib.parse import parse_qsl, unquote, unquote_to_bytes, urlencode, urlsplit, urlunsplit
@@ -22,12 +22,19 @@ from core.agent_core.ai.errors import (
classify_error,
parse_retry_after,
redact_provider_error,
+ redact_provider_text,
)
+from core.agent_core.ai.hosted import MAX_HOSTED_COUNTERS
from core.agent_core.ai.sse import SSEEvent, SSEParseError, SSEParser
from core.agent_core.cancel import CancelToken
from core.agent_core.messages import (
AssistantContent,
AssistantMessage,
+ Citation,
+ HostedCost,
+ HostedSource,
+ HostedSummary,
+ HostedToolBlock,
ImageBlock,
Origin,
TextBlock,
@@ -65,7 +72,8 @@ class ServedHop:
class ServedResolution:
"""The response origin, whether its signature data is verified, and its Source.
- ``source_id`` is ``None`` in direct mode and for a missing or invalid report.
+ ``source_id`` is the endpoint's own Source in direct mode (``None`` when it names none), and ``None`` for a
+ missing or invalid served-hop report.
"""
origin: Origin
@@ -114,6 +122,10 @@ MAX_CUMULATIVE_OUTPUT_CHARS = 32 * 1024 * 1024
# Conservative structural allowances, not a one-byte item counter. These cover
# block/tool objects and their indexing sets/maps in addition to payload bytes.
BLOCK_SLOT_OVERHEAD_BYTES = 2048
+#: What one retained citation costs beyond its text fields.
+CITATION_OVERHEAD_BYTES = 256
+#: What one kept hosted counter costs beyond its name.
+COUNTER_OVERHEAD_BYTES = 64
TOOL_ALIAS_OVERHEAD_BYTES = 512
# Only late response closes are detached; retain them until bounded cleanup
# completes. The driver registers their ownership in its single finally.
@@ -192,6 +204,13 @@ class StreamAssembler:
self._sensitive_values = tuple(value for value in sensitive_values if value)
self.content: list[AssistantContent] = []
self.usage: Any = None
+ #: The Source that served the response (the served-hop report): the ``native.source_id`` of its hosted calls.
+ self.source_id: str | None = None
+ self._citations: dict[int, list[Citation]] = {}
+ self._hosted_inputs: dict[Hashable, io.StringIO] = {}
+ self._hosted_counts: dict[str, int] = {}
+ self._hosted_cited: tuple[HostedSource, ...] = ()
+ self._hosted_cost: HostedCost | None = None
self._terminal_seen = False
self._emitted_output = False
# Text or a tool call: output past which a dropped response is never retried.
@@ -229,9 +248,10 @@ class StreamAssembler:
return self._emitted_output
- def set_origin(self, origin: Origin, verified_origin: bool) -> None:
+ def set_origin(self, origin: Origin, verified_origin: bool, source_id: str | None = None) -> None:
self.origin = origin
self.verified_origin = verified_origin
+ self.source_id = source_id
def begin_driver(self) -> None:
"""Defer terminal marking while the shared lifecycle driver runs."""
@@ -331,7 +351,8 @@ class StreamAssembler:
self._materialize_thinking_details(key)
for index, block in enumerate(self.content):
if isinstance(block, TextBlock):
- self.content[index] = TextBlock(text=self._text_value(index))
+ text = self._text_value(index)
+ self.content[index] = TextBlock(text=text, citations=self._text_citations(index, text))
elif isinstance(block, ThinkingBlock):
self.content[index] = ThinkingBlock(
text=self._thinking_value(index),
@@ -339,6 +360,113 @@ class StreamAssembler:
redacted=block.redacted,
)
+ def _text_citations(self, index: int, text: str) -> tuple[Citation, ...] | None:
+ """A text block's citations; a range that does not lie in its final text keeps its source, not the range."""
+
+ citations = tuple(
+ item if item.end is None or item.end <= len(text) else replace(item, start=None, end=None)
+ for item in self._citations.get(index, ())
+ )
+ return citations or None
+
+ def add_text_citation(self, key: Hashable, citation: Citation) -> None:
+ """A provider citation on the text slot ``key`` (presentation only, never replayed)."""
+
+ index = self._ensure_slot("text", key, TextBlock(text=""))
+ self._account_output(CITATION_OVERHEAD_BYTES)
+ for value in (citation.url, citation.title, citation.cited_text):
+ if value:
+ self._account_output(value)
+ self._citations.setdefault(index, []).append(citation)
+
+ def has_text_citations(self, key: Hashable) -> bool:
+ index = self._slots.get(("text", key))
+ return index is not None and bool(self._citations.get(index))
+
+ def text_citations(self) -> tuple[Citation, ...]:
+ return tuple(item for index in sorted(self._citations) for item in self._citations[index])
+
+ def hosted_block(self, key: Hashable, block: HostedToolBlock) -> None:
+ """Place a hosted call in stream order at its slot ``key``, or replace the call already there: a result
+ arriving later finalizes the same block.
+
+ This is the hosted calls' one boundary. The request's own credentials are removed from every string the block
+ retains, payload included, as exact literals: a replayed payload must stay byte-exact, so no pattern touches
+ it. The record's error is also redacted as a provider error is. Everything the block retains is charged, a
+ replacement by its growth.
+ """
+
+ if self._sensitive_values:
+ block = _without_literals(block, self._sensitive_values)
+ if block.record.error is not None:
+ redacted = redact_provider_text(
+ block.record.error, literal_secrets=self._sensitive_values, endpoint_url=self._endpoint_url
+ )
+ block = replace(block, record=replace(block.record, error=redacted or block.record.error))
+ index = self._slots.get(("hosted", key))
+ if index is None:
+ self._account_output(_retained_bytes(block))
+ self._ensure_slot("hosted", key, block)
+ else:
+ previous = self.content[index]
+ growth = _retained_bytes(block) - (
+ _retained_bytes(previous) if isinstance(previous, HostedToolBlock) else 0
+ )
+ self._account_output(max(0, growth))
+ self.content[index] = block
+ self._emitted_output = True
+ self._emitted_visible = True
+
+ def hosted_input_delta(self, key: Hashable, value: str) -> None:
+ """A fragment of a hosted call's streamed input, charged like any other retained output."""
+
+ self._account_output(value)
+ buffer = self._hosted_inputs.get(key)
+ if buffer is None:
+ buffer = self._hosted_inputs[key] = _string_buffer()
+ buffer.write(value)
+
+ def hosted_input(self, key: Hashable) -> str:
+ """The hosted call's whole streamed input, once its block ends."""
+
+ buffer = self._hosted_inputs.pop(key, None)
+ return buffer.getvalue() if buffer is not None else ""
+
+ def hosted_block_at(self, key: Hashable) -> HostedToolBlock | None:
+ index = self._slots.get(("hosted", key))
+ block = self.content[index] if index is not None else None
+ return block if isinstance(block, HostedToolBlock) else None
+
+ def set_hosted_facts(
+ self,
+ *,
+ counts: Mapping[str, int] | None = None,
+ cost: HostedCost | None = None,
+ cited: tuple[HostedSource, ...] | None = None,
+ ) -> None:
+ """The response-scoped hosted facts the provider reported (§4.2 ``hosted_summary``), each charged as it is
+ kept. A summary holds a small fixed set of counters, so at most ``MAX_HOSTED_COUNTERS`` are kept."""
+
+ if counts is not None:
+ kept = dict(list(counts.items())[:MAX_HOSTED_COUNTERS])
+ for name in kept:
+ self._account_output(COUNTER_OVERHEAD_BYTES)
+ self._account_output(name)
+ self._hosted_counts = kept
+ if cost is not None:
+ self._hosted_cost = cost
+ if cited is not None:
+ for item in cited:
+ self._account_output(CITATION_OVERHEAD_BYTES)
+ self._account_output(item.url)
+ self._account_output(item.title or "")
+ self._hosted_cited = cited
+
+ def _hosted_summary(self, content: list[AssistantContent]) -> HostedSummary | None:
+ if not any(isinstance(block, HostedToolBlock) for block in content):
+ return None
+ return HostedSummary(counts=self._hosted_counts, cited_sources=self._hosted_cited, cost=self._hosted_cost)
+
def text_delta(self, key: Hashable, value: str) -> TextDelta | None:
if not value:
return None
@@ -974,6 +1102,7 @@ class StreamAssembler:
usage=self.usage,
error_message=error_message,
verified_origin=self.verified_origin,
+ hosted_summary=self._hosted_summary(final),
)
def partial(self, *, stop_reason: str = "error") -> AssistantMessage | None:
@@ -989,6 +1118,7 @@ class StreamAssembler:
usage=self.usage,
verified_origin=self.verified_origin,
stop_reason=stop_reason,
+ hosted_summary=self._hosted_summary(content),
)
def error(
@@ -1137,6 +1267,36 @@ class StreamAssembler:
self._allocated_tool_ids.add(value)
+def _without_literals(value: Any, secrets: tuple[str, ...]) -> Any:
+ """``value`` with each of ``secrets`` replaced in every string it holds, dataclass fields included."""
+
+ if isinstance(value, str):
+ for secret in secrets:
+ value = value.replace(secret, "[redacted]")
+ return value
+ if isinstance(value, tuple):
+ return tuple(_without_literals(item, secrets) for item in value)
+ if isinstance(value, list):
+ return [_without_literals(item, secrets) for item in value]
+ if isinstance(value, dict):
+ scrubbed: dict[Any, Any] = {}
+ for key, item in value.items():
+ name = _without_literals(key, secrets)
+ while name in scrubbed: # two keys that differed only by a credential keep both, in order
+ name = f"{name}#"
+ scrubbed[name] = _without_literals(item, secrets)
+ return scrubbed
+ if is_dataclass(value) and not isinstance(value, type):
+ return replace(value, **{f.name: _without_literals(getattr(value, f.name), secrets) for f in fields(value)})
+ return value
+
+
+def _retained_bytes(block: HostedToolBlock) -> int:
+ """What a hosted call keeps: its action, record and native payload, serialized once."""
+
+ return len(json.dumps(asdict(block), ensure_ascii=False, default=str).encode("utf-8"))
+
+
def endpoint_origin(endpoint: ModelEndpoint) -> Origin:
provider = endpoint.provider or f"endpoint:{credential_free_endpoint_identity(endpoint.base_url)}"
if provider == "endpoint:":
@@ -1335,7 +1495,8 @@ async def resolve_served_origin(
direct = endpoint_origin(endpoint)
if not gateway:
- return ServedResolution(direct, True, None)
+ # Without a gateway the endpoint is the served hop, and its Source, when it names one, served the response.
+ return ServedResolution(direct, True, endpoint.source_id)
candidate = resolver(headers) if resolver is not None else default_served_hop_resolver(headers)
if inspect.isawaitable(candidate):
try:
@@ -1590,7 +1751,7 @@ async def drive_sse_stream(
if resolved_origin is None:
candidate = assembler.aborted(cancel.reason)
else:
- assembler.set_origin(resolved_origin.origin, resolved_origin.verified)
+ assembler.set_origin(resolved_origin.origin, resolved_origin.verified, resolved_origin.source_id)
async for item in translate(iter_sse_events(response, cancel)):
if isinstance(item, (Done, ProviderError)):
candidate = item
@@ -1929,6 +2090,7 @@ def assistant_message(
usage: Any = None,
error_message: str | None = None,
verified_origin: bool = True,
+ hosted_summary: HostedSummary | None = None,
) -> AssistantMessage:
if not verified_origin:
sanitized: list[AssistantContent] = []
@@ -1939,15 +2101,21 @@ def assistant_message(
sanitized.append(replace(block, signature=None))
elif isinstance(block, ToolCallBlock):
sanitized.append(replace(block, signature=None))
+ elif isinstance(block, HostedToolBlock):
+ # A hosted call is its native payload, opaque provider content that no unverified origin replays.
+ continue
else:
sanitized.append(block)
content = sanitized
+ if not any(isinstance(block, HostedToolBlock) for block in content):
+ hosted_summary = None
return AssistantMessage(
content=tuple(content),
origin=origin,
stop_reason=stop_reason, # type: ignore[arg-type]
usage=usage,
error_message=error_message,
+ hosted_summary=hosted_summary,
)
@@ -1979,6 +2147,7 @@ def partial_message(
usage: Any = None,
verified_origin: bool = True,
stop_reason: str = "aborted",
+ hosted_summary: HostedSummary | None = None,
) -> AssistantMessage:
if stop_reason in {"aborted", "error"}:
content = [block for block in content if not isinstance(block, ToolCallBlock)]
@@ -1988,6 +2157,7 @@ def partial_message(
stop_reason=stop_reason,
usage=usage,
verified_origin=verified_origin,
+ hosted_summary=hosted_summary,
)
diff --git a/core/agent_core/ai/anthropic.py b/core/agent_core/ai/anthropic.py
index cbc667af8..f7da4535b 100644
--- a/core/agent_core/ai/anthropic.py
+++ b/core/agent_core/ai/anthropic.py
@@ -15,6 +15,7 @@ from typing import Any
import httpx
+from core.agent_core.ai.hosted import anthropic_hosted_block, citation, reported_counts
from core.agent_core.ai._common import (
ServedHopResolver,
WireRequest,
@@ -246,6 +247,10 @@ class AnthropicAdapter(ProviderAdapter):
stop_reason: str | None = None
message_started = False
message_stopped = False
+ # The hosted tools this request declared natively; ``server_tool_use`` blocks of other tools stay unparsed.
+ hosted = frozenset(native_hosted_tools(request))
+ # Each hosted call's ``server_tool_use`` by stream index; its input JSON streams into the assembler.
+ uses: dict[int, dict[str, Any]] = {}
try:
async def translate(events: AsyncIterator[Any]) -> AsyncIterator[Any]:
nonlocal message_started, message_stopped, stop_reason
@@ -353,6 +358,9 @@ class AnthropicAdapter(ProviderAdapter):
assembler.set_usage(
_anthropic_usage(message.get("usage"))
)
+ start_usage = message.get("usage")
+ if isinstance(start_usage, Mapping) and "server_tool_use" in start_usage:
+ assembler.set_hosted_facts(counts=reported_counts(start_usage.get("server_tool_use")))
elif event_type == "content_block_start":
index = _stream_index(chunk)
if index is None:
@@ -394,9 +402,33 @@ class AnthropicAdapter(ProviderAdapter):
yield terminal
return
continue
+ if kind == "server_tool_use":
+ hosted_call = block.get("name") in hosted and isinstance(block.get("id"), str) and block["id"]
+ if hosted_call and assembler.source_id is not None:
+ # The call keeps its place in the stream; its input streams in and its result follows.
+ assembler.set_block_kind(index, "hosted_use")
+ uses[index] = dict(block)
+ assembler.hosted_block(
+ ("hosted", block.get("id")),
+ anthropic_hosted_block(block, None, source_id=assembler.source_id),
+ )
+ continue
+ if kind == "web_search_tool_result":
+ use = next((item for item in uses.values() if item.get("id") == block.get("tool_use_id")), None)
+ if use is not None and assembler.source_id is not None:
+ assembler.set_block_kind(index, "hosted_result")
+ assembler.hosted_block(
+ ("hosted", use.get("id")),
+ anthropic_hosted_block(use, block, source_id=assembler.source_id),
+ )
+ continue
if kind == "text":
assembler.set_block_kind(index, "text")
assembler.ensure_text_slot(index)
+ for raw in block.get("citations") or ():
+ cited = citation(raw) if isinstance(raw, Mapping) else None
+ if cited is not None:
+ assembler.add_text_citation(index, cited)
initial = block.get("text")
if initial is not None and not isinstance(initial, str):
terminal = assembler.terminal(
@@ -595,6 +627,14 @@ class AnthropicAdapter(ProviderAdapter):
value = _string(raw_signature)
if value:
assembler.append_thinking_signature(index, value)
+ elif delta_type == "citations_delta":
+ raw_citation = delta.get("citation")
+ cited = citation(raw_citation) if isinstance(raw_citation, Mapping) else None
+ if block_kind == "text" and cited is not None:
+ assembler.add_text_citation(index, cited)
+ elif delta_type == "input_json_delta" and block_kind == "hosted_use":
+ if isinstance(delta.get("partial_json"), str):
+ assembler.hosted_input_delta(index, delta["partial_json"])
elif delta_type == "input_json_delta":
if block_kind != "tool":
continue
@@ -624,6 +664,17 @@ class AnthropicAdapter(ProviderAdapter):
if terminal is not None:
yield terminal
return
+ streamed_input = assembler.hosted_input(index) if assembler.block_kind(index) == "hosted_use" else ""
+ if streamed_input:
+ use = uses[index]
+ parsed = json_object(streamed_input)
+ use["input"] = parsed if parsed is not None else use.get("input") or {}
+ current = assembler.hosted_block_at(("hosted", use.get("id")))
+ if current is not None and current.record.status == "pending":
+ assembler.hosted_block(
+ ("hosted", use.get("id")),
+ anthropic_hosted_block(use, None, source_id=current.native.source_id),
+ )
end = assembler.block_end(index)
if end is not None:
yield end
@@ -680,6 +731,8 @@ class AnthropicAdapter(ProviderAdapter):
return
stop_reason = _normalize_stop_reason(delta.get("stop_reason"))
assembler.set_usage(_anthropic_usage(usage, current=assembler.usage))
+ if isinstance(usage, Mapping) and "server_tool_use" in usage:
+ assembler.set_hosted_facts(counts=reported_counts(usage.get("server_tool_use")))
elif event_type == "error":
shape_error = _error_event_shape_error(chunk)
if shape_error is not None:
diff --git a/core/agent_core/ai/hosted.py b/core/agent_core/ai/hosted.py
new file mode 100644
index 000000000..c8a749f21
--- /dev/null
+++ b/core/agent_core/ai/hosted.py
@@ -0,0 +1,433 @@
+"""Hosted tool calls on the wire and in portable history (``vibey-hosted-tools.md`` §4.2, §4.4, §5).
+
+Two directions, one owner each:
+
+* **Parsing.** Every item a provider emits for a hosted tool the request declared natively becomes exactly one
+ ``HostedToolBlock`` with a provider-neutral action, its per-call ``HostedRecord``, and the provider's own items
+ verbatim in ``native.payload``. An action this module does not know becomes ``other`` and is kept.
+* **Rendering.** ``record_text`` is the one function that turns a record into model-facing text: a synthetic replay
+ result, the in-place text of an in-flight call, and (with the proxy executor) a proxied call's result.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Iterable, Mapping, NamedTuple, Optional, Sequence
+from urllib.parse import urlsplit
+
+from core.agent_core.ai.errors import redact_provider_text
+from core.agent_core.messages import (
+ HOSTED_ERROR_MAX_CHARS,
+ AssistantMessage,
+ Citation,
+ HostedAction,
+ HostedCost,
+ HostedNative,
+ HostedRecord,
+ HostedSource,
+ HostedToolBlock,
+ ToolCallBlock,
+)
+
+#: xAI reports a response's cost in ticks of 1e-10 USD (``usage.cost_in_usd_ticks``).
+_USD_PER_TICK = 1e-10
+_X_HOSTS = frozenset({"x.com", "twitter.com"})
+#: The counter names a summary holds (``message.schema.json``); a provider's other keys are not counters.
+_COUNTER_NAME = re.compile(r"[a-z0-9_]{1,64}")
+#: The most counters a hosted summary keeps, and the most entries of a usage section read to find them.
+MAX_HOSTED_COUNTERS = 32
+_COUNTERS_SCANNED = 256
+_X_SEARCH_VARIANTS = {"x_keyword_search": "keyword", "x_semantic_search": "semantic"}
+#: Where an ``x_thread_fetch`` call names its thread, in the order tried.
+_THREAD_REFS = ("ref", "post_id", "thread_id", "conversation_id", "url", "id")
+
+
+# --- parsing -------------------------------------------------------------------------------------------------
+
+
+def _text(value: Any) -> Optional[str]:
+ return value if isinstance(value, str) and value else None
+
+
+def bounded_error(message: str) -> str:
+ """A record's error text: the provider's words with any credential redacted, never longer than the record allows.
+ It is persisted and replayed to later models."""
+
+ message = " ".join(redact_provider_text(message).split()) or "the provider reported no reason"
+ return message if len(message) <= HOSTED_ERROR_MAX_CHARS else message[: HOSTED_ERROR_MAX_CHARS - 1] + "…"
+
+
+def _item_error(item: Mapping[str, Any], status: str) -> str:
+ error = item.get("error")
+ if isinstance(error, Mapping):
+ error = error.get("message") or error.get("code") or error.get("type")
+ return bounded_error(error if isinstance(error, str) else f"the provider ended the call {status}")
+
+
+def _payload(*items: Mapping[str, Any]) -> tuple[dict[str, Any], ...]:
+ return tuple(json.loads(json.dumps(item)) for item in items)
+
+
+def responses_hosted_tool(item: Mapping[str, Any]) -> Optional[str]:
+ """The catalog tool a Responses output item belongs to, or None for an item that is not a hosted call."""
+
+ kind = item.get("type")
+ if kind == "web_search_call":
+ return "web_search"
+ if kind == "custom_tool_call" and str(item.get("name") or "").startswith("x_"):
+ return "x_search"
+ return None
+
+
+def responses_hosted_block(
+ item: Mapping[str, Any], *, source_id: str, call_id: str, finished: bool = True
+) -> HostedToolBlock:
+ """One Responses hosted-call item (a ``web_search_call``, or xAI's X-search ``custom_tool_call``) as its block.
+
+ ``call_id`` names the block when the item carries no id of its own. An item that has only been added
+ (``finished`` false) holds the call's place in the output order as a pending call.
+ """
+
+ tool = responses_hosted_tool(item)
+ if tool is None:
+ raise ValueError(f"not a hosted call item: {item.get('type')!r}")
+ status = item.get("status")
+ if not finished:
+ record_status = "failed" if status == "failed" else "pending"
+ elif status in ("completed", "failed", "incomplete"):
+ record_status = status
+ elif status in (None, "") and tool == "x_search":
+ # xAI's X-search calls carry no output item: the call is complete when its item is.
+ record_status = "completed"
+ else:
+ record_status = "pending"
+ error = _item_error(item, record_status) if record_status in ("failed", "incomplete") else None
+ if tool == "web_search":
+ action, sources = _web_search_action(item)
+ else:
+ action, sources = _x_search_action(item), ()
+ return HostedToolBlock(
+ id=_text(item.get("id")) or _text(item.get("call_id")) or call_id,
+ tool=tool, # type: ignore[arg-type]
+ action=action,
+ record=HostedRecord(status=record_status, error=error, sources=sources), # type: ignore[arg-type]
+ native=HostedNative(source_id=source_id, payload=_payload(item)),
+ )
+
+
+def _web_search_action(item: Mapping[str, Any]) -> tuple[HostedAction, tuple[HostedSource, ...]]:
+ action = item.get("action")
+ action = action if isinstance(action, Mapping) else {}
+ kind = action.get("type")
+ sources = tuple(
+ HostedSource(url=source["url"], title=_text(source.get("title")))
+ for source in action.get("sources") or ()
+ if isinstance(source, Mapping) and _text(source.get("url"))
+ )
+ if kind == "search":
+ queries = [query for query in action.get("queries") or () if _text(query)]
+ if not queries and _text(action.get("query")):
+ queries = [action["query"]]
+ if queries:
+ return HostedAction("search", queries=tuple(queries)), sources
+ elif kind == "open_page" and _text(action.get("url")):
+ return HostedAction("open_page", url=action["url"]), sources
+ elif kind == "find_in_page" and _text(action.get("url")) and _text(action.get("pattern")):
+ return HostedAction("find_in_page", url=action["url"], pattern=action["pattern"]), sources
+ return HostedAction("other", name=_text(kind) or "web_search_call"), sources
+
+
+def _x_search_action(item: Mapping[str, Any]) -> HostedAction:
+ name = str(item.get("name"))
+ try:
+ arguments = json.loads(item.get("input") or "{}")
+ except (TypeError, ValueError):
+ arguments = None
+ if not isinstance(arguments, Mapping):
+ return HostedAction("other", name=name)
+ query = _text(arguments.get("query"))
+ if name in _X_SEARCH_VARIANTS and query:
+ limit = arguments.get("limit")
+ if isinstance(limit, str) and limit.isdigit():
+ limit = int(limit)
+ mode = arguments.get("mode")
+ return HostedAction(
+ "x_search",
+ variant=_X_SEARCH_VARIANTS[name],
+ query=query,
+ limit=limit if isinstance(limit, int) and not isinstance(limit, bool) and limit >= 1 else None,
+ mode=mode if mode in ("Latest", "Top") else None,
+ )
+ if name == "x_user_search" and query:
+ return HostedAction("x_user_search", query=query)
+ if name == "x_thread_fetch":
+ ref = next((str(arguments[key]) for key in _THREAD_REFS if _text(str(arguments.get(key) or ""))), None)
+ if ref:
+ return HostedAction("x_thread_fetch", ref=ref)
+ return HostedAction("other", name=name)
+
+
+def anthropic_hosted_block(
+ use: Mapping[str, Any], result: Optional[Mapping[str, Any]], *, source_id: str
+) -> HostedToolBlock:
+ """An Anthropic ``server_tool_use`` named ``web_search`` and its ``web_search_tool_result``, once one arrived."""
+
+ query = _text((use.get("input") or {}).get("query")) if isinstance(use.get("input"), Mapping) else None
+ action = HostedAction("search", queries=(query,)) if query else HostedAction("other", name="web_search")
+ if result is None:
+ record = HostedRecord(status="pending")
+ else:
+ content = result.get("content")
+ if isinstance(content, list):
+ record = HostedRecord(
+ status="completed",
+ sources=tuple(
+ HostedSource(url=hit["url"], title=_text(hit.get("title")), page_age=_text(hit.get("page_age")))
+ for hit in content
+ if isinstance(hit, Mapping) and _text(hit.get("url"))
+ ),
+ )
+ else:
+ code = content.get("error_code") if isinstance(content, Mapping) else None
+ record = HostedRecord(status="failed", error=bounded_error(code if isinstance(code, str) else ""))
+ payload = (use,) if result is None else (use, result)
+ return HostedToolBlock(
+ id=str(use["id"]),
+ tool="web_search",
+ action=action,
+ record=record,
+ native=HostedNative(source_id=source_id, payload=_payload(*payload)),
+ )
+
+
+def citation(raw: Mapping[str, Any], *, offset: int = 0) -> Optional[Citation]:
+ """A provider citation on assistant text: an OpenAI/xAI ``url_citation`` with its range, shifted by ``offset``
+ into the block's text, or an Anthropic ``web_search_result_location``, which covers its whole text block."""
+
+ url = _text(raw.get("url"))
+ if url is None:
+ return None
+ title = _text(raw.get("title"))
+ # xAI titles a citation with its number ("1", "2"): that is no title.
+ title = None if title is not None and title.isdigit() else title
+ start, end = raw.get("start_index"), raw.get("end_index")
+ if isinstance(start, int) and isinstance(end, int) and not isinstance(start, bool) and 0 <= start <= end:
+ return Citation(url=url, title=title, start=offset + start, end=offset + end)
+ return Citation(url=url, title=title, cited_text=_text(raw.get("cited_text")))
+
+
+def x_cited_sources(citations: Iterable[Citation]) -> tuple[HostedSource, ...]:
+ """The posts an X-search answer cites (§4.2 ``cited_sources``): its citations to X, once each, in first-seen order."""
+
+ seen: dict[str, HostedSource] = {}
+ for item in citations:
+ try:
+ host = (urlsplit(item.url).hostname or "").lower().removeprefix("www.")
+ except ValueError:
+ continue # a URL that does not parse cites no post
+ if host in _X_HOSTS and item.url not in seen:
+ seen[item.url] = HostedSource(url=item.url, title=item.title)
+ return tuple(seen.values())
+
+
+def reported_counts(*sections: Any) -> dict[str, int]:
+ """Provider-reported hosted counters (xAI ``server_side_tool_usage_details``, Anthropic ``server_tool_use``),
+ keeping the ones that counted something."""
+
+ counts: dict[str, int] = {}
+ for section in sections:
+ if not isinstance(section, Mapping):
+ continue
+ # A summary holds a small fixed set of counters: the cap holds while collecting, over a bounded scan.
+ for scanned, (name, value) in enumerate(section.items()):
+ if len(counts) >= MAX_HOSTED_COUNTERS or scanned >= _COUNTERS_SCANNED:
+ break
+ counted = isinstance(value, int) and not isinstance(value, bool) and value > 0
+ if counted and isinstance(name, str) and _COUNTER_NAME.fullmatch(name):
+ counts[name] = value
+ return counts
+
+
+def reported_cost(usage: Any) -> Optional[HostedCost]:
+ """The response's cost when the provider reports one (xAI ``cost_in_usd_ticks``); never a priced guess."""
+
+ ticks = usage.get("cost_in_usd_ticks") if isinstance(usage, Mapping) else None
+ if isinstance(ticks, int) and not isinstance(ticks, bool) and ticks >= 0:
+ return HostedCost(basis="reported", usd=ticks * _USD_PER_TICK)
+ return None
+
+
+# --- rendering (§3.4, §4.4, §5) --------------------------------------------------------------------------------
+
+
+def record_text(
+ tool: str,
+ record: HostedRecord,
+ *,
+ query: Optional[str],
+ further_queries: Sequence[str] = (),
+ notes: Sequence[str] = (),
+ cited: Sequence[HostedSource] = (),
+) -> str:
+ """The model-facing text of one finished hosted call: its status line first, then everything it carries.
+
+ A failed or incomplete record says so first (``[<tool> failed: <error>]``), so no protocol without an error flag
+ can read it as an empty success. Whatever the status, every line attached to the call follows: further queries,
+ folded actions, the sources it found (titles, links, excerpts and ages) and the posts its answer cites.
+ """
+
+ if record.status in ("failed", "incomplete"):
+ lines = [f"[{tool} failed: {record.error}]"]
+ if query:
+ lines.append(f"Query: {json.dumps(query, ensure_ascii=False)}")
+ else:
+ lines = [f"[{tool}: {json.dumps(query, ensure_ascii=False)}]" if query else f"[{tool}]"]
+ if further_queries:
+ lines.append("Also searched: " + "; ".join(json.dumps(item, ensure_ascii=False) for item in further_queries))
+ lines.extend(notes)
+ lines.extend(_numbered(record.sources))
+ if cited:
+ lines.append("Posts cited in the answer:")
+ lines.extend(_numbered(cited))
+ if record.status == "completed" and not record.sources and not cited and not notes:
+ lines.append("No results were returned.")
+ return "\n".join(lines)
+
+
+def _numbered(sources: Sequence[HostedSource]) -> list[str]:
+ lines: list[str] = []
+ for number, source in enumerate(sources, 1):
+ lines.append(f"{number}. {source.title or source.url}")
+ if source.title:
+ lines.append(f" {source.url}")
+ if source.snippet:
+ lines.append(f" {source.snippet}")
+ if source.page_age:
+ lines.append(f" Published: {source.page_age}")
+ return lines
+
+
+def action_note(action: HostedAction) -> str:
+ """A non-search action as a line in the result of its tool's preceding call."""
+
+ if action.type == "open_page":
+ return f"Opened {action.url}"
+ if action.type == "find_in_page":
+ return f"Searched {action.url} for {json.dumps(action.pattern, ensure_ascii=False)}"
+ if action.type == "x_thread_fetch":
+ return f"Fetched thread {action.ref}"
+ return f"Ran {action.name or action.type}"
+
+
+def call_arguments(tool: str, action: HostedAction) -> Optional[dict[str, Any]]:
+ """The synthetic same-named call's arguments for a calling action; None for a non-search action, which folds
+ into its tool's preceding call."""
+
+ if action.type == "search":
+ return {"query": (action.queries or ("",))[0]}
+ if action.type in ("x_search", "x_user_search"):
+ arguments: dict[str, Any] = {"query": action.query}
+ if action.limit is not None:
+ arguments["limit"] = action.limit
+ if action.mode is not None:
+ arguments["mode"] = action.mode
+ return arguments
+ if action.type == "generate":
+ generated: dict[str, Any] = {"prompt": action.prompt or ""}
+ if action.size is not None:
+ generated["size"] = action.size
+ return generated
+ return None
+
+
+def standalone_query(action: HostedAction) -> str:
+ """A non-search action with no preceding call of its tool becomes its own call with this query."""
+
+ target = action.url or action.ref or action.name or ""
+ return f"{action.type} {target}".strip()
+
+
+def _unit(block: HostedToolBlock) -> tuple[dict[str, Any], tuple[str, ...]]:
+ """A hosted call's synthetic arguments, and the line a completed non-search action shows (its query names it)."""
+
+ arguments = call_arguments(block.tool, block.action)
+ if arguments is None:
+ done = block.record.status == "completed"
+ return {"query": standalone_query(block.action)}, (action_note(block.action),) if done else ()
+ return arguments, ()
+
+
+def _unit_text(block: HostedToolBlock, *, cited: Sequence[HostedSource], pending: str) -> str:
+ """The text one hosted call goes back as, in either portable form: ``pending`` for a call cut off with its turn,
+ else its record with every line attached to it."""
+
+ if block.record.status == "pending":
+ return pending
+ arguments, notes = _unit(block)
+ query = arguments.get("query") or arguments.get("prompt")
+ further = (block.action.queries or ())[1:]
+ return record_text(block.tool, block.record, query=query, further_queries=further, notes=notes, cited=cited)
+
+
+def in_place_text(block: HostedToolBlock, *, cited: Sequence[HostedSource] = ()) -> str:
+ """A hosted call replaced in place by one text block (§4.4); its status always shows."""
+
+ arguments, _ = _unit(block)
+ query = arguments.get("query") or arguments.get("prompt")
+ return _unit_text(block, cited=cited, pending=f"[{block.tool}: {json.dumps(query, ensure_ascii=False)}] (no result)")
+
+
+class PortableHosted(NamedTuple):
+ """How one hosted call goes back in portable form: a synthetic same-named ``call`` with its result, or
+ ``in_place`` as one text block."""
+
+ kind: str
+ name: str = ""
+ arguments: Mapping[str, Any] = {}
+ text: str = ""
+ is_error: bool = False
+
+
+def portable_hosted(message: AssistantMessage, *, in_flight: bool, interrupted: str) -> dict[int, PortableHosted]:
+ """Each hosted call of a replayed response in portable form (§4.4, §5), keyed by the block's identity.
+
+ Every call is exactly one unit with its own record:
+ * in place as text, for a response its turn still waits on, and for any call that follows a client tool call of
+ the same response (a split there would separate that call from its result);
+ * otherwise a synthetic same-named call and its result.
+
+ The posts the answer cites are listed once, on its first call that was not cut off, whichever form it takes.
+ ``interrupted`` is the result of a synthetic call cut off with its turn.
+ """
+
+ blocks = [block for block in message.content if isinstance(block, HostedToolBlock)]
+ summary = message.hosted_summary
+ owner = next((block for block in blocks if block.record.status != "pending"), None)
+ plan: dict[int, PortableHosted] = {}
+ in_place = in_flight
+ for block in message.content:
+ if not isinstance(block, HostedToolBlock):
+ in_place = in_place or isinstance(block, ToolCallBlock)
+ continue
+ cited = summary.cited_sources if summary is not None and block is owner else ()
+ if in_place:
+ plan[id(block)] = PortableHosted("in_place", text=in_place_text(block, cited=cited))
+ continue
+ arguments, _ = _unit(block)
+ failed = block.record.status in ("failed", "incomplete", "pending")
+ text = _unit_text(block, cited=cited, pending=interrupted)
+ plan[id(block)] = PortableHosted("call", block.tool, arguments, text, failed)
+ return plan
+
+
+def portable_sizes(message: AssistantMessage, *, interrupted: str) -> dict[int, int]:
+ """What each hosted call of ``message`` costs on the wire in UTF-8 bytes, by the block's identity: the larger of
+ its two portable forms, so an estimate holds wherever the message sits in a request."""
+
+ sizes: dict[int, int] = {}
+ for in_flight in (False, True):
+ for key, unit in portable_hosted(message, in_flight=in_flight, interrupted=interrupted).items():
+ arguments = json.dumps(dict(unit.arguments), ensure_ascii=False, separators=(",", ":")) if unit.kind == "call" else ""
+ sizes[key] = max(sizes.get(key, 0), len((unit.name + arguments + unit.text).encode("utf-8")))
+ return sizes
diff --git a/core/agent_core/ai/openai_responses.py b/core/agent_core/ai/openai_responses.py
index afe7b2d19..fb877c67e 100644
--- a/core/agent_core/ai/openai_responses.py
+++ b/core/agent_core/ai/openai_responses.py
@@ -15,6 +15,14 @@ from typing import Any
import httpx
+from core.agent_core.ai.hosted import (
+ citation,
+ reported_cost,
+ reported_counts,
+ responses_hosted_block,
+ responses_hosted_tool,
+ x_cited_sources,
+)
from core.agent_core.ai._common import (
ServedHopResolver,
WireRequest,
@@ -49,6 +57,7 @@ from core.agent_core.ai.provider import (
from core.agent_core.cancel import CancelToken
from core.agent_core.messages import (
AssistantMessage,
+ HostedToolBlock,
TextBlock,
ThinkingBlock,
ToolCallBlock,
@@ -329,6 +338,8 @@ class OpenAIResponsesAdapter(ProviderAdapter):
status: str | None = None
incomplete_reason: str | None = None
refusal = False
+ # The hosted tools this request declared natively: only their items become hosted calls (§4.2).
+ hosted = frozenset(native_hosted_tools(request))
try:
wire = wire_request(request, transformed_messages, gateway=self._gateway, loaded_images=loaded_images)
@@ -631,6 +642,9 @@ class OpenAIResponsesAdapter(ProviderAdapter):
assembler.merge_reasoning_item(output_index, item)
elif item_type == "message":
assembler.ensure_text_slot(output_index)
+ else:
+ # A hosted call takes its place in the output order now; its done item fills it in.
+ _add_hosted_call(assembler, item, output_index, hosted, finished=False)
elif event_type == "response.reasoning_summary_text.done":
continue
elif event_type == "response.reasoning_summary_part.done":
@@ -916,9 +930,12 @@ class OpenAIResponsesAdapter(ProviderAdapter):
if emitted is not None:
yield emitted
refusal = refusal or message_refusal
+ _add_message_citations(assembler, output_index, item)
end = assembler.block_end(output_index)
if end is not None:
yield end
+ else:
+ _add_hosted_call(assembler, item, output_index, hosted)
elif event_type in {"response.completed", "response.incomplete"}:
response_body = chunk.get("response")
if not isinstance(response_body, Mapping):
@@ -1019,21 +1036,8 @@ class OpenAIResponsesAdapter(ProviderAdapter):
yield terminal
return
response_error = response_value
- output = response_body.get("output")
- if output is not None and not isinstance(output, list):
- terminal = assembler.terminal(
- assembler.error(
- f"{event_type} response output must be an array",
- kind="invalid_request",
- )
- )
- if terminal is not None:
- yield terminal
- return
- terminal_output_error, terminal_refusal = _apply_terminal_output_items(
- output,
- assembler,
- reasoning,
+ terminal_output_error, terminal_refusal = _finish_response(
+ response_body, event_type, assembler, reasoning, hosted
)
refusal = refusal or terminal_refusal
if terminal_output_error is not None:
@@ -1180,6 +1184,13 @@ class OpenAIResponsesAdapter(ProviderAdapter):
yield terminal
return
assembler.set_usage(_responses_usage(response_body.get("usage")))
+ # The calls it ran before failing were billed: its partial keeps them and what they cost.
+ finish_error, _ = _finish_response(response_body, event_type, assembler, reasoning, hosted)
+ if finish_error is not None:
+ terminal = assembler.terminal(finish_error)
+ if terminal is not None:
+ yield terminal
+ return
elif "error" in chunk and chunk.get("error") is not None and not isinstance(
chunk.get("error"), Mapping
):
@@ -1457,6 +1468,7 @@ def _apply_terminal_output_items(
items: Any,
assembler: StreamAssembler,
reasoning: set[int],
+ hosted: frozenset[str] = frozenset(),
) -> tuple[ProviderError | None, bool]:
if not isinstance(items, list):
return None, False
@@ -1489,9 +1501,95 @@ def _apply_terminal_output_items(
refusal = refusal or message_refusal
if message_refusal and assembler.has_text_slot(index):
_append_message_refusal(assembler, index, item)
+ if assembler.has_text_slot(index) and not assembler.has_text_citations(index):
+ _add_message_citations(assembler, index, item)
+ else:
+ # A hosted call this stream never finished in ``output_item.done``; one it did keeps its block.
+ _add_hosted_call(assembler, item, index, hosted, backfill=True)
return None, refusal
+def _finish_response(
+ response_body: Mapping[str, Any],
+ event_type: str,
+ assembler: StreamAssembler,
+ reasoning: set[int],
+ hosted: frozenset[str],
+) -> tuple[ProviderError | None, bool]:
+ """What every terminal Response carries beyond its status, read once for completed, incomplete and failed alike:
+ the hosted facts in its usage, the output items the stream did not finish, and the posts its answer cites.
+
+ Returns an error for an output that is not an array, or an item that does not parse, and whether a refusal came
+ back.
+ """
+
+ _set_hosted_facts(assembler, response_body.get("usage"))
+ output = response_body.get("output")
+ if output is not None and not isinstance(output, list):
+ return assembler.error(f"{event_type} response output must be an array", kind="invalid_request"), False
+ error, refusal = _apply_terminal_output_items(output, assembler, reasoning, hosted)
+ _cite_x_posts(assembler)
+ return error, refusal
+
+
+def _cite_x_posts(assembler: StreamAssembler) -> None:
+ """An X-search answer's cited posts (§4.2): the response gives none per call, so its summary holds them."""
+
+ if any(isinstance(block, HostedToolBlock) and block.tool == "x_search" for block in assembler.content):
+ assembler.set_hosted_facts(cited=x_cited_sources(assembler.text_citations()))
+
+
+def _add_hosted_call(
+ assembler: StreamAssembler,
+ item: Mapping[str, Any],
+ output_index: int,
+ hosted: frozenset[str],
+ *,
+ finished: bool = True,
+ backfill: bool = False,
+) -> None:
+ """An output item of a hosted tool the request declared natively, as its hosted call at its output index (§4.2):
+ pending when only added, filled in when done. A call the terminal response backfills keeps a block it has.
+
+ A response whose served Source is unknown keeps no hosted call: its native payload could never be replayed.
+ """
+
+ tool = responses_hosted_tool(item)
+ if tool is None or tool not in hosted or assembler.source_id is None:
+ return
+ current = assembler.hosted_block_at(output_index)
+ if backfill and current is not None and current.record.status != "pending":
+ return
+ assembler.hosted_block(
+ output_index,
+ responses_hosted_block(
+ item, source_id=assembler.source_id, call_id=f"hosted_{output_index}", finished=finished
+ ),
+ )
+
+
+def _add_message_citations(assembler: StreamAssembler, index: int, item: Mapping[str, Any]) -> None:
+ """``url_citation`` annotations on a message's text parts, as citations into the text the parts make together."""
+
+ offset = 0
+ for part in item.get("content") or ():
+ if not isinstance(part, Mapping):
+ continue
+ for annotation in part.get("annotations") or ():
+ if isinstance(annotation, Mapping) and annotation.get("type") == "url_citation":
+ cited = citation(annotation, offset=offset)
+ if cited is not None:
+ assembler.add_text_citation(index, cited)
+ offset += len(_string(part.get("text")) or _string(part.get("refusal")))
+
+
+def _set_hosted_facts(assembler: StreamAssembler, usage: Any) -> None:
+ """What the provider reported about the response's hosted calls: its counters and, from xAI, its cost."""
+
+ details = usage.get("server_side_tool_usage_details") if isinstance(usage, Mapping) else None
+ assembler.set_hosted_facts(counts=reported_counts(details), cost=reported_cost(usage))
+
+
def _message_has_refusal(item: Mapping[str, Any]) -> bool:
value = item.get("content")
if not isinstance(value, list):
diff --git a/core/agent_core/ai/transform.py b/core/agent_core/ai/transform.py
index 1bf37b2a2..d69283204 100644
--- a/core/agent_core/ai/transform.py
+++ b/core/agent_core/ai/transform.py
@@ -12,9 +12,11 @@ import re
from dataclasses import dataclass
from typing import Any, Mapping
+from core.agent_core.ai.hosted import portable_hosted
from core.agent_core.messages import (
AssistantMessage,
AssistantContent,
+ HostedToolBlock,
ImageBlock,
Message,
Origin,
@@ -76,6 +78,9 @@ def transform_messages(
"""
target_protocol = protocol or target.api
+ # The request's last assistant message still awaits its turn's next response when it stopped for tools: its
+ # hosted calls stay in place as text (§4.4); every earlier one becomes a synthetic call and result (§5).
+ last_assistant = max((i for i, m in enumerate(messages) if isinstance(m, AssistantMessage)), default=-1)
id_map: dict[str, str] = {}
used_tool_ids: set[str] = set()
tool_id_occurrences: dict[str, int] = {}
@@ -83,7 +88,7 @@ def transform_messages(
suppressed_tool_result_ids: set[str] = set()
transformed: list[Message] = []
- for message in messages:
+ for position, message in enumerate(messages):
if isinstance(message, UserMessage):
pending_tool_ids.clear()
suppressed_tool_result_ids.clear()
@@ -118,7 +123,41 @@ def transform_messages(
same_origin = message.origin == target
content: list[AssistantContent] = []
turn_tool_ids: dict[str, list[str]] = {}
+ in_flight = position == last_assistant and message.stop_reason == "tool_use"
+ hosted = portable_hosted(message, in_flight=in_flight, interrupted=SYNTHETIC_TOOL_RESULT)
+ # The synthetic results of the current run of hosted calls, and the assistant parts they split off.
+ results: list[ToolResultMessage] = []
+ parts: list[Message] = []
+
+ def split() -> None:
+ nonlocal content, results
+ if results:
+ parts.append(_assistant_part(message, content, stop_reason="tool_use"))
+ parts.extend(results)
+ content, results = [], []
+
for block in message.content:
+ if isinstance(block, HostedToolBlock):
+ portable = hosted[id(block)]
+ if portable.kind == "in_place":
+ split()
+ content.append(TextBlock(text=portable.text))
+ continue
+ name, arguments, text, is_error = portable.name, dict(portable.arguments), portable.text, portable.is_error
+ call_id = _claim_tool_call_id(
+ block.id,
+ normalize_tool_call_id(block.id, target_protocol),
+ used_tool_ids=used_tool_ids,
+ occurrences=tool_id_occurrences,
+ )
+ content.append(ToolCallBlock(id=call_id, name=name, arguments=arguments))
+ results.append(
+ ToolResultMessage(
+ tool_call_id=call_id, tool_name=name, content=(TextBlock(text=text),), is_error=is_error
+ )
+ )
+ continue
+ split()
if isinstance(block, ThinkingBlock):
if block.redacted:
if same_origin:
@@ -165,20 +204,25 @@ def transform_messages(
continue
for source_id, wire_ids in turn_tool_ids.items():
pending_tool_ids.setdefault(source_id, []).extend(wire_ids)
- transformed.append(
- AssistantMessage(
- content=tuple(content),
- origin=message.origin,
- stop_reason=message.stop_reason,
- usage=message.usage,
- error_message=message.error_message,
- )
- )
+ split()
+ transformed.extend(parts)
+ if content or not parts:
+ transformed.append(_assistant_part(message, content, stop_reason=message.stop_reason))
transformed = _insert_synthetic_results(transformed)
return TransformResult(messages=tuple(transformed), tool_call_id_map=dict(id_map))
+def _assistant_part(message: AssistantMessage, content: list[AssistantContent], *, stop_reason: str) -> AssistantMessage:
+ return AssistantMessage(
+ content=tuple(content),
+ origin=message.origin,
+ stop_reason=stop_reason, # type: ignore[arg-type]
+ usage=message.usage,
+ error_message=message.error_message,
+ )
+
+
def transform_messages_for_target(
messages: list[Message] | tuple[Message, ...],
target: Origin,
diff --git a/core/agent_core/harness/context.py b/core/agent_core/harness/context.py
index 55ebad1bb..e7cf3ed23 100644
--- a/core/agent_core/harness/context.py
+++ b/core/agent_core/harness/context.py
@@ -23,11 +23,14 @@ from dataclasses import dataclass, field
from typing import Any, Callable, Collection, Mapping, Optional, Protocol, Sequence
from core.agent_core.ai._common import endpoint_origin, native_hosted_tools
+from core.agent_core.ai.hosted import portable_sizes
+from core.agent_core.ai.transform import SYNTHETIC_TOOL_RESULT
from core.agent_core.ai.provider import HostedToolRoute, ModelCapabilities, ModelEndpoint, ModelRequest
from core.agent_core.harness.projection import ContextView, Unit, context_view
from core.agent_core.harness.store import ContextEntry
from core.agent_core.messages import (
AssistantMessage,
+ HostedToolBlock,
ImageBlock,
Message,
TextBlock,
@@ -243,6 +246,8 @@ def message_tokens(message: Message) -> int:
images = 0
signed = 0 # thinking text that rides with a payload: the reported reasoning covers it
payload: Optional[int] = None # UTF-8 bytes of its opaque payloads, None without any
+ hosted_bytes = 0 # UTF-8 bytes of its hosted calls as replayed
+ hosted: Optional[dict[int, int]] = None
for block in message.content:
if isinstance(block, TextBlock):
size += _utf8(block.text) if block.text is not None else block.ref.bytes
@@ -259,8 +264,14 @@ def message_tokens(message: Message) -> int:
size += _utf8(block.name) + _utf8(arguments)
if block.signature is not None:
payload = (payload or 0) + _utf8(block.signature)
+ elif isinstance(block, HostedToolBlock):
+ # Replayed in portable form, never as its native payload (§5): the larger of its synthetic call and
+ # result and its in-place text, so the estimate holds wherever the message sits.
+ if hosted is None:
+ hosted = portable_sizes(message, interrupted=SYNTHETIC_TOOL_RESULT) # type: ignore[arg-type]
+ hosted_bytes += hosted[id(block)]
reasoning = 0 if payload is None else max(math.ceil(signed / 4), _reasoning(message, payload))
- return math.ceil(size / 4) + images * IMAGE_TOKENS + reasoning
+ return math.ceil((size + hosted_bytes) / 4) + images * IMAGE_TOKENS + reasoning
def _reasoning(message: Message, payload: int) -> int:
diff --git a/docs/plans/agent-core-contracts/conversion-tables.md b/docs/plans/agent-core-contracts/conversion-tables.md
index 9bafec1e7..bf5c7ab22 100644
--- a/docs/plans/agent-core-contracts/conversion-tables.md
+++ b/docs/plans/agent-core-contracts/conversion-tables.md
@@ -645,9 +645,22 @@ Responses terminal states:
Planned by [`../vibey-hosted-tools.md`](../vibey-hosted-tools.md) (Phase 1: `web_search`, `x_search`,
`image_generation`). These rows describe the wire mapping the `ai` lane implements with that phase. Implemented so
-far: a hosted tool's canonical spec is sent as the native declaration on a hop whose route is native, with its
-Responses `include` values and the pin header on that request. Until the rest lands the adapters ignore hosted items, as the sections above record, and the Anthropic stop
-table above still maps `pause_turn` to `stop`.
+far:
+
+- **Requests.** A hosted tool's canonical spec is sent as the native declaration on a hop whose route is native, with
+ its Responses `include` values and the pin header on that request.
+- **Parsing** for `web_search` and `x_search`: native results become `HostedToolBlock`s, text citations become
+ `TextBlock.citations`, and response-level facts go to `hosted_summary`.
+- **Portable history.** A finished response's hosted calls become synthetic same-named calls and results, split around
+ the assistant message. There is one call per hosted block, and nothing folds. Each result shows its status line
+ first and then every line attached to it. A response its
+ turn is still waiting on (the request's last assistant message, stopped for tools) keeps each call in place as text.
+ So does a hosted call that follows a client tool call of the same response, because a split there would separate
+ that call from its result.
+
+Still to come: native verbatim replay, the `pin_unavailable` re-render, `pause_turn`, the proxy executor and images.
+Until `pause_turn` lands, the Anthropic stop table above still maps it to `stop`. An Anthropic citation covers its
+whole text block, so it carries no range.
| Concern | Anthropic Messages | OpenAI Responses (OpenAI, xAI) | OpenAI Chat Completions |
| --- | --- | --- | --- |
diff --git a/docs/plans/agent-core-contracts/provider.md b/docs/plans/agent-core-contracts/provider.md
index 2d1520f1d..9ed450c2c 100644
--- a/docs/plans/agent-core-contracts/provider.md
+++ b/docs/plans/agent-core-contracts/provider.md
@@ -83,7 +83,8 @@ token names an immutable snapshot (`message.schema.json`), so the bytes never ch
(C-6), which the gateway sends as the `x-avibe-served-hop` response header: compact JSON with exactly `provider`,
`api`, `model`, `source` (Model Hub contract v12), before the first model byte. The `origin` is `provider`, `api`,
`model`; `source` is the serving Source id, which is not part of a message's origin. A report of any other shape
-counts as no report. On the direct channel (no gateway) the endpoint is the served hop. When a gateway response carries no
+counts as no report. On the direct channel (no gateway) the endpoint is the served hop, and its `source_id`, when it
+names one, is the serving Source. When a gateway response carries no
served-hop report, the origin is unverified: the adapter commits the message with every opaque provider payload
removed (the `signature` of every block of any kind, and redacted thinking), keeping the endpoint as `origin`, so no
opaque payload of an unknown vendor can ever be replayed. A block without a signature is always sent without one
diff --git a/docs/plans/vibey-hosted-tools.md b/docs/plans/vibey-hosted-tools.md
index 85624c6ae..818bb7ba5 100644
--- a/docs/plans/vibey-hosted-tools.md
+++ b/docs/plans/vibey-hosted-tools.md
@@ -412,11 +412,14 @@ These rules become C-1 rows in `cross-provider.md` and per-protocol rows in `con
- An `image_generation` action becomes one `image_generation` call with `{prompt}`, plus `size` when the action
has it. Its result is the **text path record** (§7.3). Image bytes are never resent: no base64 and no image
block, even to the same Source.
- - A non-search action (`open_page`, `find_in_page`, `x_thread_fetch`, `other`) becomes a line in the result of the
- preceding synthetic call of the same tool in that response, e.g. "opened <url>" or "fetched thread <ref>".
- Without a preceding call, it becomes its own call with `{query: "<action type> <target>"}`.
- - The response's `hosted_summary.cited_sources` are listed once, in the first synthetic result of that tool, as
- "posts cited in the answer".
+ - A non-search action (`open_page`, `find_in_page`, `x_thread_fetch`, `other`) is its own call with
+ `{query: "<action type> <target>"}`. A completed one's result says what it did, e.g. "Opened <url>" or "Fetched
+ thread <ref>".
+ - **Deviation (orchestrator decision, PR #2561 review).** The design first folded such an action into the result
+ of its tool's preceding call. Each rendering defect found in review came from that folding, where a line could
+ land on a result that does not show it. So every hosted block is exactly one call, with its own status.
+ - The response's `hosted_summary.cited_sources` are listed once, as "posts cited in the answer". They go on the
+ first call that was not cut off, whether it is replayed as a synthetic call or in place.
- A `failed` or `incomplete` record renders as an error result: Anthropic `is_error: true`, or text starting
`[<tool> failed: <error>]` where the protocol has no error flag.
- A `pending` record (a call cut off with the turn) renders as the C-1 interrupted-call result.
diff --git a/modules/agents/vibey/tools.py b/modules/agents/vibey/tools.py
index 312badba6..b8f9c9fa6 100644
--- a/modules/agents/vibey/tools.py
+++ b/modules/agents/vibey/tools.py
@@ -113,6 +113,11 @@ class NativeHostedTool:
return ToolResult(content=(TextBlock(f"{self.spec.name} is not available on this route."),), is_error=True)
+#: The hosted tools whose native results the adapters parse. A generated image arrives as base64 that history must
+#: never hold (§7.3), so ``image_generation`` joins with its media handling.
+PARSED_HOSTED_TOOLS = ("web_search", "x_search")
+
+
def native_hosted_tools(selection: Optional[ModelSelection]) -> tuple[Tool, ...]:
"""The hosted tools preflight's hop runs natively, in Model Hub's order. They lead the Turn's tools, so its last
tool stays a local one whatever a hop renders them as."""
@@ -120,4 +125,8 @@ def native_hosted_tools(selection: Optional[ModelSelection]) -> tuple[Tool, ...]
if selection is None:
return ()
routes = selection.endpoint.hosted_tools
- return tuple(NativeHostedTool(hosted_tool_spec(name)) for name, route in routes.items() if route.mode == "native")
+ return tuple(
+ NativeHostedTool(hosted_tool_spec(name))
+ for name, route in routes.items()
+ if route.mode == "native" and name in PARSED_HOSTED_TOOLS
+ )
diff --git a/tests/agent_core/agent/test_compaction.py b/tests/agent_core/agent/test_compaction.py
index 1859f5ab5..b9a2ce1b5 100644
--- a/tests/agent_core/agent/test_compaction.py
+++ b/tests/agent_core/agent/test_compaction.py
@@ -56,6 +56,12 @@ from core.agent_core.harness.context import (
from core.agent_core.harness.projection import context_view, project
from core.agent_core.messages import (
AssistantMessage,
+ HostedAction,
+ HostedCost,
+ HostedNative,
+ HostedRecord,
+ HostedSummary,
+ HostedToolBlock,
Origin,
TextBlock,
ThinkingBlock,
@@ -74,6 +80,7 @@ from tests.agent_core.fakes import (
FakeModelRouter,
FakeTool,
InMemoryTranscriptStore,
+ ORIGIN,
WINDOW_REFUSAL,
anthropic_error,
assistant,
@@ -719,6 +726,28 @@ async def test_the_checkpoint_usage_keeps_every_reported_field():
assert agent.store.audits[0][2]["usage"] == expected
+async def test_a_hosted_call_a_checkpoint_turn_makes_is_recorded_with_its_cost_and_the_checkpoint_holds():
+ """MH-HOSTED-VIBEY-002, C-10 F2: a side turn keeps the native hosted declarations, so a provider may run a hosted
+ call during a checkpoint. That call cannot be denied at execution; it is parsed like any other, kept in the turn's
+ audit with its reported cost, and the checkpoint text beside it still holds."""
+ search = HostedToolBlock(
+ id="srvtoolu_1",
+ tool="web_search",
+ action=HostedAction("search", queries=("release notes",)),
+ record=HostedRecord(status="completed"),
+ native=HostedNative(source_id="src_served00001", payload=({"type": "server_tool_use", "id": "srvtoolu_1"},)),
+ )
+ summary = HostedSummary(counts={"web_search_requests": 1}, cost=HostedCost(basis="reported", usd=0.01))
+ reply = AssistantMessage((search, text(CHECKPOINT)), ORIGIN, "stop", hosted_summary=summary)
+ agent = make_agent(Model(after_checkpoint(), [[Done(reply)]]), tools=[reader(tokens(3_000))], selection=ROOMY)
+ await run(agent)
+ assert (await cross(agent))[-1].reason == "completed"
+ assert [row for row in await agent.store.load("session") if row.kind == "compaction"]
+ audited = agent.store.audits[0][2]["messages"][-1]
+ assert audited["content"][0]["type"] == "hosted_tool"
+ assert audited["hosted_summary"]["cost"] == {"basis": "reported", "usd": 0.01}
+
+
async def test_failing_checkpoints_stop_after_two_in_a_run_and_the_next_run_tries_again():
store = InMemoryTranscriptStore()
model = Model(reads(7), FAILURES[:2])
diff --git a/tests/agent_core/agent/test_context.py b/tests/agent_core/agent/test_context.py
index 13d7f6d9a..dd386a3de 100644
--- a/tests/agent_core/agent/test_context.py
+++ b/tests/agent_core/agent/test_context.py
@@ -57,6 +57,12 @@ from core.agent_core.tools.base import ToolSpec
from core.agent_core.tools.hosted import hosted_tool_spec
from core.agent_core.messages import (
AssistantMessage,
+ HostedAction,
+ HostedNative,
+ HostedRecord,
+ HostedSource,
+ HostedSummary,
+ HostedToolBlock,
ImageBlock,
TextBlock,
ThinkingBlock,
@@ -118,6 +124,23 @@ def test_the_estimate_counts_utf8_bytes_so_chinese_is_not_undercounted():
assert message_tokens(reply) == math.ceil(replayed / 4)
+def test_a_hosted_call_counts_as_the_call_and_result_it_is_replayed_as_never_as_its_opaque_payload():
+ """A hosted call goes back as a synthetic call and its result text, not its native payload (§5), so that is what
+ it costs: an opaque Anthropic search result of 18 KB would otherwise overcount and compact early, and the call's
+ arguments, which repeat its query, would go uncounted."""
+ search = HostedToolBlock(
+ id="srvtoolu_1",
+ tool="web_search",
+ action=HostedAction("search", queries=("q",)),
+ record=HostedRecord(status="completed", sources=(HostedSource(url="https://a.test"),)),
+ native=HostedNative(source_id="src_served00001", payload=({"encrypted_content": "x" * 18_000},)),
+ )
+ reply = AssistantMessage((search,), ORIGIN, "stop", hosted_summary=HostedSummary())
+ arguments = '{"query":"q"}'
+ rendered = '[web_search: "q"]\n1. https://a.test'
+ assert message_tokens(reply) == math.ceil((len("web_search") + len(arguments) + len(rendered)) / 4)
+
+
def responses_item(reasoning: int, summary: str = "") -> ThinkingBlock:
"""An OpenAI Responses reasoning item as the adapter stores it: about 17 bytes of ciphertext per reasoning token."""
ciphertext = base64.b64encode(bytes(range(256)) * (reasoning // 15 + 1)).decode()[: 17 * reasoning]
diff --git a/tests/agent_core/ai/test_hosted_parsing.py b/tests/agent_core/ai/test_hosted_parsing.py
new file mode 100644
index 000000000..882752d88
--- /dev/null
+++ b/tests/agent_core/ai/test_hosted_parsing.py
@@ -0,0 +1,517 @@
+"""Hosted-call parsing (``vibey-hosted-tools.md`` §4.2), read from stub provider streams. Scenario MH-HOSTED-VIBEY-002.
+
+Every item a provider emits for a hosted tool the request declared natively becomes exactly one ``HostedToolBlock``
+in stream order, with a provider-neutral action, its per-call record and the provider's items verbatim. Citations
+belong to the text that cites them; response-scoped facts go to ``hosted_summary``. The stream shapes are the
+2026-10-13 spike's, redacted.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+import core.agent_core.ai._common as common_module
+from core.agent_core.ai._common import OutputBudgetExceeded, StreamAssembler
+from core.agent_core.ai.hosted import reported_counts, responses_hosted_block
+from core.agent_core.ai.provider import Done, HostedToolRoute, ModelEndpoint, ModelRequest
+from core.agent_core.ai.registry import create_adapter
+from core.agent_core.cancel import CancelToken
+from core.agent_core.messages import (
+ AssistantMessage,
+ HostedSummary,
+ message_to_dict,
+ Citation,
+ HostedAction,
+ HostedCost,
+ HostedSource,
+ HostedToolBlock,
+ Origin,
+ TextBlock,
+ ToolCallBlock,
+ UserMessage,
+)
+from core.agent_core.tools.hosted import hosted_tool_spec
+
+SERVED = "src_served00001"
+ORIGIN_X = Origin("upstream", "openai_responses", "model-x")
+WEB, X = hosted_tool_spec("web_search"), hosted_tool_spec("x_search")
+NATIVE = {
+ "web_search": HostedToolRoute("native", None, False, declaration={"type": "web_search"}),
+ "x_search": HostedToolRoute("native", None, False, declaration={"type": "x_search"}),
+}
+
+
+def _sse(*events: dict[str, Any]) -> str:
+ return "".join(f"data: {json.dumps(event)}\n\n" for event in events)
+
+
+async def _message(
+ protocol: str,
+ body: str,
+ *,
+ hosted: dict[str, HostedToolRoute] = NATIVE,
+ tools=(WEB, X),
+ served: bool = True,
+) -> AssistantMessage:
+ request = ModelRequest(
+ endpoint=ModelEndpoint(
+ protocol, # type: ignore[arg-type]
+ "http://hub.invalid/vibey/v1",
+ "model-x",
+ "hub-token",
+ provider="upstream",
+ source_id=SERVED,
+ hosted_tools=hosted,
+ ),
+ system="system",
+ messages=(UserMessage((TextBlock("search"),)),),
+ tools=tools,
+ max_tokens=256,
+ )
+ headers = {"content-type": "text/event-stream"}
+ if served:
+ headers["x-avibe-served-hop"] = json.dumps(
+ {"provider": "upstream", "api": protocol, "model": "served-model", "source": SERVED}, separators=(",", ":")
+ )
+
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(lambda _: httpx.Response(200, headers=headers, text=body))
+ ) as client:
+ adapter = create_adapter(protocol, client=client, gateway=True) # type: ignore[arg-type]
+ events = [event async for event in adapter.stream(request, CancelToken())]
+ assert isinstance(events[-1], Done), events[-1]
+ return events[-1].message
+
+
+# --- OpenAI Responses (OpenAI, xAI) ---------------------------------------------------------------------------
+
+WEB_SEARCH_CALL = {
+ "id": "ws_1",
+ "type": "web_search_call",
+ "status": "completed",
+ "action": {
+ "type": "search",
+ "query": "CLIProxyAPI latest release",
+ "sources": [{"type": "url", "url": "https://github.com/router-for-me/CLIProxyAPI/releases"}],
+ },
+}
+ANSWER = "The latest release is v8.0.27.[[1]](https://github.com/router-for-me/CLIProxyAPI/releases)"
+ANSWER_ITEM = {
+ "id": "msg_1",
+ "type": "message",
+ "content": [
+ {
+ "type": "output_text",
+ "text": ANSWER,
+ "annotations": [
+ {
+ "type": "url_citation",
+ "url": "https://github.com/router-for-me/CLIProxyAPI/releases",
+ "start_index": 29,
+ "end_index": len(ANSWER),
+ "title": "1",
+ }
+ ],
+ }
+ ],
+}
+
+
+def _responses(
+ items: list[dict[str, Any]], usage: dict[str, Any], *, done_order: list[int] | None = None, repeat: bool = True
+) -> str:
+ """Every item added in output order, then done in ``done_order``; the terminal response repeats them unless
+ ``repeat`` is false."""
+
+ events: list[dict[str, Any]] = [{"type": "response.created", "response": {"status": "in_progress"}}]
+ for index, item in enumerate(items):
+ events.append({"type": "response.output_item.added", "output_index": index, "item": {**item, "status": "in_progress"}})
+ if item["type"] == "web_search_call":
+ # Progress frames are not model output and change nothing.
+ events.append({"type": "response.web_search_call.searching", "output_index": index, "item_id": item["id"]})
+ if item["type"] == "message":
+ events.append({"type": "response.output_text.delta", "output_index": index, "delta": item["content"][0]["text"]})
+ for index in done_order if done_order is not None else range(len(items)):
+ events.append({"type": "response.output_item.done", "output_index": index, "item": items[index]})
+ # The terminal response repeats every item; none is parsed twice.
+ output = items if repeat else None
+ events.append({"type": "response.completed", "response": {"status": "completed", "output": output, "usage": usage}})
+ return _sse(*events)
+
+
+async def test_an_xai_web_search_is_one_hosted_call_with_its_sources_cited_text_and_reported_cost():
+ """MH-HOSTED-VIBEY-002: one hosted call per item, its sources per call, the citation on the text that cites it,
+ and the response's counters and reported cost once in its summary; the terminal copy is never parsed twice."""
+ usage = {
+ "input_tokens": 22965,
+ "output_tokens": 1402,
+ "cost_in_usd_ticks": 277316400,
+ "server_side_tool_usage_details": {"web_search_calls": 1, "x_search_calls": 0},
+ }
+
+ message = await _message("openai_responses", _responses([WEB_SEARCH_CALL, ANSWER_ITEM], usage))
+
+ call, answer = message.content
+ assert call == HostedToolBlock(
+ id="ws_1",
+ tool="web_search",
+ action=HostedAction("search", queries=("CLIProxyAPI latest release",)),
+ record=call.record,
+ native=call.native,
+ )
+ assert call.record.status == "completed"
+ assert call.record.sources == (HostedSource(url="https://github.com/router-for-me/CLIProxyAPI/releases"),)
+ assert call.native.source_id == SERVED and call.native.payload == (WEB_SEARCH_CALL,)
+ # xAI titles a citation with its number, which is no title.
+ assert answer == TextBlock(
+ text=ANSWER,
+ citations=(Citation(url="https://github.com/router-for-me/CLIProxyAPI/releases", start=29, end=len(ANSWER)),),
+ )
+ summary = message.hosted_summary
+ assert summary.counts == {"web_search_calls": 1}
+ assert summary.cost.basis == "reported" and summary.cost.usd == pytest.approx(0.02773164)
+ assert summary.cited_sources == ()
+ assert message.stop_reason == "stop"
+
+
[email protected]("repeat", [True, False], ids=["terminal-output", "no-terminal-output"])
+async def test_xai_x_searches_keep_their_variants_and_the_answer_cites_each_post_once(repeat):
+ calls = [
+ {
+ "type": "custom_tool_call",
+ "id": f"ctc_{n}",
+ "call_id": f"xs_call-{n}",
+ "name": name,
+ "input": json.dumps(arguments),
+ "status": "completed",
+ }
+ for n, (name, arguments) in enumerate(
+ [
+ ("x_keyword_search", {"query": "from:OpenAI within_time:7d", "limit": "10", "mode": "Latest"}),
+ ("x_semantic_search", {"query": "GPT-6 launch"}),
+ ]
+ )
+ ]
+ post, other_post = "https://x.com/OpenAI/status/1", "https://twitter.com/OpenAI/status/2"
+ text = "[[1]](post1)[[2]](post2) OpenAI posted. [[1]](post1)"
+ message_item = {
+ "id": "msg_1",
+ "type": "message",
+ "content": [
+ {
+ "type": "output_text",
+ "text": text,
+ "annotations": [
+ {"type": "url_citation", "url": post, "start_index": 0, "end_index": 12, "title": "1"},
+ {"type": "url_citation", "url": other_post, "start_index": 12, "end_index": 24, "title": "2"},
+ {"type": "url_citation", "url": post, "start_index": 40, "end_index": 52, "title": "1"},
+ ],
+ }
+ ],
+ }
+ # xAI's encrypted X-search output rides in a ``tco_`` reasoning item, which stays thinking.
+ reasoning = {"type": "reasoning", "id": "tco_1", "summary": [], "encrypted_content": "opaque"}
+ usage = {
+ "input_tokens": 14987,
+ "output_tokens": 2907,
+ "cost_in_usd_ticks": 1127268800,
+ "server_side_tool_usage_details": {"x_search_calls": 2, "x_posts_fetched": 20, "web_search_calls": 0},
+ }
+
+ message = await _message("openai_responses", _responses([*calls, reasoning, message_item], usage, repeat=repeat))
+
+ keyword, semantic = (block for block in message.content if isinstance(block, HostedToolBlock))
+ assert keyword.action == HostedAction(
+ "x_search", variant="keyword", query="from:OpenAI within_time:7d", limit=10, mode="Latest"
+ )
+ assert semantic.action == HostedAction("x_search", variant="semantic", query="GPT-6 launch")
+ assert keyword.record.sources == () and keyword.record.status == "completed"
+ assert not any(isinstance(block, ToolCallBlock) for block in message.content)
+ summary = message.hosted_summary
+ assert summary.counts == {"x_search_calls": 2, "x_posts_fetched": 20}
+ assert summary.cited_sources == (HostedSource(url=post), HostedSource(url=other_post))
+ assert summary.cost.usd == pytest.approx(0.11272688)
+
+
+ ("item", "action", "status"),
+ [
+ # ``queries`` wins over the deprecated singular ``query``.
+ (
+ {"type": "web_search_call", "status": "completed", "action": {"type": "search", "queries": ["a", "b"], "query": "a"}},
+ HostedAction("search", queries=("a", "b")),
+ "completed",
+ ),
+ (
+ {"type": "web_search_call", "status": "completed", "action": {"type": "open_page", "url": "https://a.test"}},
+ HostedAction("open_page", url="https://a.test"),
+ "completed",
+ ),
+ (
+ {
+ "type": "web_search_call",
+ "status": "completed",
+ "action": {"type": "find_in_page", "url": "https://a.test", "pattern": "v8"},
+ },
+ HostedAction("find_in_page", url="https://a.test", pattern="v8"),
+ "completed",
+ ),
+ # An action this design does not know is kept as ``other``, never dropped.
+ (
+ {"type": "web_search_call", "status": "completed", "action": {"type": "scroll"}},
+ HostedAction("other", name="scroll"),
+ "completed",
+ ),
+ (
+ {"type": "custom_tool_call", "name": "x_user_search", "input": '{"query": "OpenAI"}', "status": "completed"},
+ HostedAction("x_user_search", query="OpenAI"),
+ "completed",
+ ),
+ (
+ {"type": "custom_tool_call", "name": "x_thread_fetch", "input": '{"post_id": "12"}', "status": "completed"},
+ HostedAction("x_thread_fetch", ref="12"),
+ "completed",
+ ),
+ (
+ {"type": "custom_tool_call", "name": "x_media_search", "input": '{"query": "cats"}', "status": "completed"},
+ HostedAction("other", name="x_media_search"),
+ "completed",
+ ),
+ (
+ {"type": "web_search_call", "status": "failed", "action": {"type": "search", "query": "a"}},
+ HostedAction("search", queries=("a",)),
+ "failed",
+ ),
+ ],
+ ids=["queries", "open_page", "find_in_page", "unknown-action", "x_user_search", "x_thread_fetch", "unknown-x", "failed"],
+)
+def test_the_mapping_rule_gives_every_responses_item_a_provider_neutral_action(item, action, status):
+ block = responses_hosted_block({"id": "item_1", **item}, source_id=SERVED, call_id="hosted_0")
+
+ assert (block.action, block.record.status) == (action, status)
+ assert (block.record.error is not None) == (status == "failed")
+ assert block.native.payload == ({"id": "item_1", **item},)
+
+
[email protected](("hosted", "served"), [({}, True), (NATIVE, False)], ids=["not-declared", "unknown-source"])
+async def test_no_hosted_call_without_a_native_declaration_or_a_known_serving_source(hosted, served):
+ """A hosted item for a tool the request did not declare natively is not a hosted call of this request, and a
+ response whose serving Source is unknown keeps none: its payload could never be replayed."""
+
+ message = await _message(
+ "openai_responses", _responses([WEB_SEARCH_CALL, ANSWER_ITEM], {"input_tokens": 1}), hosted=hosted, served=served
+ )
+
+ assert [type(block) for block in message.content] == [TextBlock]
+ assert message.hosted_summary is None
+
+
+# --- Anthropic Messages -------------------------------------------------------------------------------------
+
+
+def _anthropic(*blocks: list[dict[str, Any]], stop_reason: str = "end_turn", server_tool_use: int = 1) -> str:
+ events: list[dict[str, Any]] = [{"type": "message_start", "message": {"usage": {"input_tokens": 6}}}]
+ for index, frames in enumerate(blocks):
+ events.extend({**frame, "index": index} for frame in frames)
+ events.append({"type": "content_block_stop", "index": index})
+ events.append(
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": stop_reason},
+ "usage": {"output_tokens": 519, "server_tool_use": {"web_search_requests": server_tool_use, "web_fetch_requests": 0}},
+ }
+ )
+ events.append({"type": "message_stop"})
+ return _sse(*events)
+
+
+def _use(call_id: str, query: str) -> list[dict[str, Any]]:
+ half = len(query) // 2
+ return [
+ {"type": "content_block_start", "content_block": {"type": "server_tool_use", "id": call_id, "name": "web_search", "input": {}}},
+ {"type": "content_block_delta", "delta": {"type": "input_json_delta", "partial_json": f'{{"query": "{query[:half]}'}},
+ {"type": "content_block_delta", "delta": {"type": "input_json_delta", "partial_json": f'{query[half:]}"}}'}},
+ ]
+
+
+def _result(call_id: str, content: Any) -> list[dict[str, Any]]:
+ return [{"type": "content_block_start", "content_block": {"type": "web_search_tool_result", "tool_use_id": call_id, "content": content}}]
+
+
+HIT = {
+ "type": "web_search_result",
+ "title": "Releases · router-for-me/CLIProxyAPI",
+ "url": "https://github.com/router-for-me/CLIProxyAPI/releases",
+ "encrypted_content": "opaque",
+ "page_age": "15 days ago",
+}
+LOCATION = {
+ "type": "web_search_result_location",
+ "url": HIT["url"],
+ "title": HIT["title"],
+ "cited_text": "v8.0.24 Latest",
+ "encrypted_index": "opaque",
+}
+
+
+async def test_an_anthropic_search_and_its_result_are_one_hosted_call_and_the_text_keeps_its_citation():
+ text = [
+ {"type": "content_block_start", "content_block": {"type": "text", "text": ""}},
+ {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "The latest release is v8.0.24."}},
+ {"type": "content_block_delta", "delta": {"type": "citations_delta", "citation": LOCATION}},
+ ]
+
+ message = await _message("anthropic", _anthropic(_use("srvtoolu_1", "CLIProxyAPI releases"), _result("srvtoolu_1", [HIT]), text), tools=(WEB,))
+
+ call, answer = message.content
+ assert call.action == HostedAction("search", queries=("CLIProxyAPI releases",))
+ assert call.record.status == "completed"
+ assert call.record.sources == (HostedSource(url=HIT["url"], title=HIT["title"], page_age="15 days ago"),)
+ use = {"type": "server_tool_use", "id": "srvtoolu_1", "name": "web_search", "input": {"query": "CLIProxyAPI releases"}}
+ result = {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_1", "content": [HIT]}
+ assert call.native.payload == (use, result)
+ # An Anthropic citation covers its whole text block, so it carries no range.
+ assert answer == TextBlock(
+ text="The latest release is v8.0.24.",
+ citations=(Citation(url=HIT["url"], title=HIT["title"], cited_text="v8.0.24 Latest"),),
+ )
+ assert message.hosted_summary.counts == {"web_search_requests": 1}
+ assert message.hosted_summary.cost is None # unknown is never priced as zero
+
+
+async def test_parallel_anthropic_searches_finalize_by_id_and_a_search_cut_off_stays_pending():
+ client_call = [
+ {"type": "content_block_start", "content_block": {"type": "tool_use", "id": "toolu_1", "name": "read", "input": {}}},
+ {"type": "content_block_delta", "delta": {"type": "input_json_delta", "partial_json": '{"path": "a"}'}},
+ ]
+ failed = {"type": "web_search_tool_result_error", "error_code": "max_uses_exceeded"}
+
+ message = await _message(
+ "anthropic",
+ _anthropic(
+ _use("srvtoolu_a", "first"),
+ _use("srvtoolu_b", "second"),
+ _use("srvtoolu_c", "third"),
+ _result("srvtoolu_b", [HIT]),
+ _result("srvtoolu_a", failed),
+ client_call,
+ stop_reason="tool_use",
+ server_tool_use=2,
+ ),
+ tools=(WEB,),
+ )
+
+ first, second, third, read = message.content
+ assert [first.id, second.id, third.id] == ["srvtoolu_a", "srvtoolu_b", "srvtoolu_c"]
+ assert (first.record.status, first.record.error) == ("failed", "max_uses_exceeded")
+ assert second.record.status == "completed"
+ assert third.record.status == "pending" and len(third.native.payload) == 1
+ assert read == ToolCallBlock(id="toolu_1", name="read", arguments={"path": "a"}, native_id="toolu_1")
+ assert message.stop_reason == "tool_use"
+
+
+async def test_parallel_responses_calls_keep_their_output_order_whatever_order_they_finish_in():
+ second = {**WEB_SEARCH_CALL, "id": "ws_2", "action": {"type": "search", "query": "second"}}
+
+ message = await _message(
+ "openai_responses", _responses([WEB_SEARCH_CALL, second, ANSWER_ITEM], {"input_tokens": 1}, done_order=[1, 0, 2])
+ )
+
+ assert [getattr(block, "id", "text") for block in message.content] == ["ws_1", "ws_2", "text"]
+ assert all(block.record.status == "completed" for block in message.content[:2])
+
+
+def test_a_hosted_error_is_redacted_before_the_record_keeps_it():
+ """The record is persisted and replayed to later models, so a provider's echoed credential never reaches it."""
+
+ secret = "sk-proj-" + "a1B2c3D4e5F6" * 4
+ item = {"id": "ws_1", "type": "web_search_call", "status": "failed", "error": {"message": f"bad key {secret}"}}
+
+ block = responses_hosted_block(item, source_id=SERVED, call_id="hosted_0")
+
+ assert block.record.status == "failed" and secret not in block.record.error
+
+
+ "retain",
+ [
+ lambda assembler: assembler.hosted_input_delta(0, "q" * 16384),
+ lambda assembler: assembler.add_text_citation(0, Citation(url="https://a.test", cited_text="c" * 16384)),
+ lambda assembler: assembler.hosted_block(
+ 0, responses_hosted_block({**WEB_SEARCH_CALL, "padding": "p" * 16384}, source_id=SERVED, call_id="h")
+ ),
+ # The payload alone fits; its canonical copies in the action and record do not.
+ lambda assembler: assembler.hosted_block(
+ 0,
+ responses_hosted_block(
+ {
+ **WEB_SEARCH_CALL,
+ "action": {"type": "search", "query": "q" * 2500, "sources": [{"type": "url", "url": "https://" + "u" * 2500}]},
+ },
+ source_id=SERVED,
+ call_id="h",
+ ),
+ ),
+ ],
+ ids=["streamed-input", "citation", "payload", "canonical-copies"],
+)
+def test_every_byte_a_hosted_call_or_citation_keeps_counts_against_the_output_budget(monkeypatch, retain):
+ monkeypatch.setattr(common_module, "MAX_CUMULATIVE_OUTPUT_CHARS", 8192)
+ assembler = StreamAssembler(origin=Origin("upstream", "anthropic", "model-x"), protocol="anthropic")
+
+ with pytest.raises(OutputBudgetExceeded):
+ retain(assembler)
+
+
+def test_the_requests_own_credentials_are_in_no_string_a_hosted_call_keeps():
+ """A provider can echo a configured key no generic pattern recognises, anywhere in its item. The assembler's one
+ boundary removes it as an exact literal from everything the call keeps, its native payload included, and leaves
+ every other byte of the payload as the provider sent it."""
+
+ assembler = StreamAssembler(
+ origin=Origin("upstream", "openai_responses", "model-x"),
+ protocol="openai_responses",
+ sensitive_values=("relay-key-7",),
+ )
+ item = {
+ "id": "ws_1",
+ "type": "web_search_call",
+ "status": "failed",
+ "error": {"message": "key relay-key-7 refused"},
+ "action": {"type": "search", "query": "why relay-key-7", "sources": [{"type": "url", "url": "https://a.test/?k=relay-key-7"}]},
+ "encrypted": "sk-0123456789abcdefABCDEF0123456789",
+ "echo": {"relay-key-7": "as a key"},
+ }
+
+ assembler.hosted_block(0, responses_hosted_block(item, source_id=SERVED, call_id="h"))
+
+ kept = assembler.content[0]
+ serialized = json.dumps(message_to_dict(AssistantMessage((kept,), ORIGIN_X, "stop", hosted_summary=HostedSummary())))
+ assert "relay-key-7" not in serialized
+ # No pattern rewrote the opaque provider string a replay must send back exactly.
+ assert kept.native.payload[0]["encrypted"] == item["encrypted"]
+
+
+def test_hosted_facts_are_charged_as_kept_and_a_summary_keeps_at_most_32_counters(monkeypatch):
+ assembler = StreamAssembler(origin=ORIGIN_X, protocol="openai_responses")
+ assembler.set_origin(ORIGIN_X, True, SERVED)
+ assembler.hosted_block(0, responses_hosted_block(WEB_SEARCH_CALL, source_id=SERVED, call_id="h"))
+
+ assembler.set_hosted_facts(counts={f"counter_{n}": 1 for n in range(100)})
+
+ assert len(assembler.finalize("stop").hosted_summary.counts) == 32
+ monkeypatch.setattr(common_module, "MAX_CUMULATIVE_OUTPUT_CHARS", 8192)
+ fresh = StreamAssembler(origin=ORIGIN_X, protocol="openai_responses")
+ # About 5,000 characters, but over 12,000 UTF-8 bytes: the charge is in bytes.
+ with pytest.raises(OutputBudgetExceeded):
+ fresh.set_hosted_facts(cited=(HostedSource(url="https://x.com/" + "é" * 3000, title="中" * 2000),))
+
+
+def test_a_usage_section_of_many_counters_is_read_only_up_to_the_cap():
+ counters = {f"counter_{n}": 1 for n in range(10_000)}
+
+ assert reported_counts(counters) == {f"counter_{n}": 1 for n in range(32)}
diff --git a/tests/agent_core/ai/test_hosted_transform.py b/tests/agent_core/ai/test_hosted_transform.py
new file mode 100644
index 000000000..9481bb05e
--- /dev/null
+++ b/tests/agent_core/ai/test_hosted_transform.py
@@ -0,0 +1,389 @@
+"""Hosted calls in history (``vibey-hosted-tools.md`` §4.4, §5). Scenario MH-HOSTED-VIBEY-003.
+
+Until native replay is authorized, every hosted call goes back in portable form. A finished response's calls become
+synthetic same-named calls and results, splitting the assistant message around them, with one record-to-text
+function writing every result. A response its turn is still waiting on keeps each call in place as text. Citations
+are never sent.
+"""
+
+from __future__ import annotations
+
+import itertools
+
+import pytest
+
+from core.agent_core.ai.provider import ModelEndpoint, ModelRequest
+from core.agent_core.ai.registry import build_wire_request
+from core.agent_core.ai.transform import SYNTHETIC_TOOL_RESULT, transform_messages
+from core.agent_core.messages import (
+ AssistantMessage,
+ Citation,
+ HostedAction,
+ HostedNative,
+ HostedRecord,
+ HostedSource,
+ HostedSummary,
+ HostedToolBlock,
+ Origin,
+ TextBlock,
+ ThinkingBlock,
+ ToolCallBlock,
+ ToolResultMessage,
+ UserMessage,
+)
+
+XAI = Origin("xai", "openai_responses", "grok-4.6")
+SOURCE = "src_served00001"
+RELEASES = HostedSource(
+ url="https://github.com/router-for-me/CLIProxyAPI/releases",
+ title="Releases",
+ snippet="v8.0.27 was released on October 12.",
+ page_age="1 day ago",
+)
+
+
+def _hosted(call_id: str, tool: str, action: HostedAction, record: HostedRecord) -> HostedToolBlock:
+ return HostedToolBlock(
+ id=call_id,
+ tool=tool, # type: ignore[arg-type]
+ action=action,
+ record=record,
+ native=HostedNative(source_id=SOURCE, payload=({"type": "web_search_call", "id": call_id},)),
+ )
+
+
+SEARCH = _hosted(
+ "ws_1",
+ "web_search",
+ HostedAction("search", queries=("CLIProxyAPI latest release", "CLIProxyAPI v8")),
+ HostedRecord(status="completed", sources=(RELEASES,)),
+)
+ANSWER = TextBlock(
+ text="v8.0.27, released October 12.",
+ citations=(Citation(url=RELEASES.url, start=0, end=7),),
+)
+
+
+def _response(*content, stop_reason="stop", summary=HostedSummary()) -> AssistantMessage:
+ return AssistantMessage(tuple(content), XAI, stop_reason, hosted_summary=summary)
+
+
+def _follow_up() -> UserMessage:
+ return UserMessage((TextBlock("And who published it?"),))
+
+
+SEARCH_TEXT = (
+ '[web_search: "CLIProxyAPI latest release"]\n'
+ 'Also searched: "CLIProxyAPI v8"\n'
+ "1. Releases\n"
+ " https://github.com/router-for-me/CLIProxyAPI/releases\n"
+ " v8.0.27 was released on October 12.\n"
+ " Published: 1 day ago"
+)
+
+
+ ("protocol", "expected"),
+ [
+ (
+ "anthropic",
+ [
+ {"role": "user", "content": "search"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "tool_use", "id": "ws_1", "name": "web_search", "input": {"query": "CLIProxyAPI latest release"}}
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {"type": "tool_result", "tool_use_id": "ws_1", "content": [{"type": "text", "text": SEARCH_TEXT}], "is_error": False}
+ ],
+ },
+ {"role": "assistant", "content": [{"type": "text", "text": ANSWER.text}]},
+ {"role": "user", "content": "And who published it?"},
+ ],
+ ),
+ (
+ "openai_responses",
+ [
+ {"role": "user", "content": [{"type": "input_text", "text": "search"}]},
+ {"type": "function_call", "call_id": "ws_1", "name": "web_search", "arguments": '{"query": "CLIProxyAPI latest release"}'},
+ {"type": "function_call_output", "call_id": "ws_1", "output": SEARCH_TEXT},
+ {"role": "assistant", "content": [{"type": "output_text", "text": ANSWER.text}]},
+ {"role": "user", "content": [{"type": "input_text", "text": "And who published it?"}]},
+ ],
+ ),
+ (
+ "openai_chat",
+ [
+ {"role": "user", "content": "search"},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {"id": "ws_1", "type": "function", "function": {"name": "web_search", "arguments": '{"query": "CLIProxyAPI latest release"}'}}
+ ],
+ },
+ {"role": "tool", "tool_call_id": "ws_1", "content": SEARCH_TEXT},
+ {"role": "assistant", "content": ANSWER.text},
+ {"role": "user", "content": "And who published it?"},
+ ],
+ ),
+ ],
+)
+async def test_a_replayed_search_is_a_synthetic_same_named_call_and_result_on_every_protocol(protocol, expected):
+ history = (UserMessage((TextBlock("search"),)), _response(SEARCH, ANSWER), _follow_up())
+ request = ModelRequest(
+ endpoint=ModelEndpoint(protocol, "http://hub.invalid/vibey/v1", "model-x", "hub-token", provider="other"), # type: ignore[arg-type]
+ system="system",
+ messages=history,
+ tools=(),
+ max_tokens=256,
+ cache="none",
+ )
+
+ wire = await build_wire_request(request, gateway=True)
+
+ sent = wire.body["messages"] if protocol != "openai_responses" else wire.body["input"]
+ sent = [message for message in sent if message.get("role") != "system"]
+ assert _comparable(sent, expected) == expected
+
+
+def _comparable(sent: list[dict], expected: list[dict]) -> list[dict]:
+ """The sent items reduced to the keys the expectation names (ids and the like may carry more)."""
+
+ def reduce(value, shape):
+ if isinstance(shape, dict) and isinstance(value, dict):
+ return {key: reduce(value.get(key), shape[key]) for key in shape}
+ if isinstance(shape, list) and isinstance(value, list) and len(shape) == len(value):
+ return [reduce(item, item_shape) for item, item_shape in zip(value, shape)]
+ return value
+
+ return [reduce(item, shape) for item, shape in zip(sent, expected)] + sent[len(expected) :]
+
+
+def _transformed(*history):
+ return list(transform_messages(history, target=Origin("anthropic", "anthropic", "claude-opus-5-5")))
+
+
+def test_every_hosted_call_is_its_own_synthetic_call_and_a_page_action_says_what_it_did():
+ """§5 as implemented (option b): no action folds into another call's result. A page action is its own call whose
+ query names it, and its completed result says what it did."""
+
+ opened = _hosted(
+ "ws_2",
+ "web_search",
+ HostedAction("open_page", url="https://example.test/notes"),
+ HostedRecord(status="completed"),
+ )
+
+ _, calls, search, page, *_ = _transformed(UserMessage((TextBlock("go"),)), _response(SEARCH, opened, ANSWER), _follow_up())
+
+ assert [(block.name, block.arguments) for block in calls.content] == [
+ ("web_search", {"query": "CLIProxyAPI latest release"}),
+ ("web_search", {"query": "open_page https://example.test/notes"}),
+ ]
+ assert search.content[0].text == SEARCH_TEXT
+ assert page.content[0].text == '[web_search: "open_page https://example.test/notes"]\nOpened https://example.test/notes'
+
+
+ ("record", "text", "is_error"),
+ [
+ (HostedRecord(status="failed", error="max_uses_exceeded"), '[web_search failed: max_uses_exceeded]\nQuery: "q"', True),
+ (HostedRecord(status="incomplete", error="cut off"), '[web_search failed: cut off]\nQuery: "q"', True),
+ (HostedRecord(status="pending"), SYNTHETIC_TOOL_RESULT, True),
+ (HostedRecord(status="completed"), '[web_search: "q"]\nNo results were returned.', False),
+ ],
+ ids=["failed", "incomplete", "pending", "empty"],
+)
+def test_a_failed_or_cut_off_call_never_reads_as_a_successful_empty_result(record, text, is_error):
+ block = _hosted("ws_9", "web_search", HostedAction("search", queries=("q",)), record)
+
+ _, _, result, *_ = _transformed(UserMessage((TextBlock("go"),)), _response(block, ANSWER), _follow_up())
+
+ assert (result.content[0].text, result.is_error) == (text, is_error)
+
+
+def test_the_posts_an_x_answer_cites_are_listed_once_in_its_first_x_search_result():
+ post = HostedSource(url="https://x.com/OpenAI/status/1")
+ searches = [
+ _hosted(f"ctc_{n}", "x_search", HostedAction("x_search", variant="keyword", query=f"q{n}"), HostedRecord(status="completed"))
+ for n in range(2)
+ ]
+
+ messages = _transformed(
+ UserMessage((TextBlock("go"),)),
+ _response(*searches, ANSWER, summary=HostedSummary(counts={"x_search_calls": 2}, cited_sources=(post,))),
+ _follow_up(),
+ )
+
+ results = [message for message in messages if isinstance(message, ToolResultMessage)]
+ assert [post.url in result.content[0].text for result in results] == [True, False]
+ assert results[0].content[0].text.endswith("Posts cited in the answer:\n1. https://x.com/OpenAI/status/1")
+
+
+def test_a_response_its_turn_still_waits_on_keeps_each_call_in_place_as_text():
+ """§4.4: within a turn, a hosted call stays where it was, as one text block, and signed thinking stays intact."""
+
+ thinking = ThinkingBlock(text="", signature="signed")
+ read = ToolCallBlock(id="toolu_1", name="read", arguments={"path": "a"})
+ running = AssistantMessage((thinking, SEARCH, read), Origin("anthropic", "anthropic", "claude-opus-5-5"), "tool_use", hosted_summary=HostedSummary())
+
+ user, sent, result = _transformed(
+ UserMessage((TextBlock("go"),)), running, ToolResultMessage("toolu_1", "read", (TextBlock("contents"),))
+ )
+
+ assert sent.content == (thinking, TextBlock(text=SEARCH_TEXT), read)
+ assert result.tool_call_id == "toolu_1"
+
+
+ ("action", "record", "text"),
+ [
+ (
+ HostedAction("open_page", url="https://a.test"),
+ HostedRecord(status="failed", error="timeout"),
+ '[web_search failed: timeout]\nQuery: "open_page https://a.test"',
+ ),
+ (HostedAction("find_in_page", url="https://a.test", pattern="v8"), HostedRecord(status="pending"), None),
+ (
+ HostedAction("open_page", url="https://a.test"),
+ HostedRecord(status="completed"),
+ '[web_search: "open_page https://a.test"]\nOpened https://a.test',
+ ),
+ ],
+ ids=["failed", "pending", "completed"],
+)
+def test_an_in_flight_non_search_action_keeps_its_status_in_place(action, record, text):
+ """A failed or unfinished page action in a running turn never reads as done."""
+
+ block = _hosted("ws_5", "web_search", action, record)
+ running = AssistantMessage(
+ (block, ToolCallBlock(id="toolu_1", name="read", arguments={})),
+ Origin("anthropic", "anthropic", "claude-opus-5-5"),
+ "tool_use",
+ hosted_summary=HostedSummary(),
+ )
+
+ _, sent, _ = _transformed(
+ UserMessage((TextBlock("go"),)), running, ToolResultMessage("toolu_1", "read", (TextBlock("contents"),))
+ )
+
+ rendered = sent.content[0].text
+ if text is None:
+ assert rendered.endswith("(no result)") and "Opened" not in rendered and "Searched" not in rendered
+ else:
+ assert rendered == text
+
+
[email protected]("status", ["failed", "pending"])
+def test_a_page_action_that_did_not_complete_is_its_own_failed_call_never_a_line_in_the_previous_result(status):
+ record = HostedRecord(status="failed", error="timeout") if status == "failed" else HostedRecord(status="pending")
+ opened = _hosted("ws_2", "web_search", HostedAction("open_page", url="https://example.test/notes"), record)
+
+ messages = _transformed(UserMessage((TextBlock("go"),)), _response(SEARCH, opened, ANSWER), _follow_up())
+
+ results = [message for message in messages if isinstance(message, ToolResultMessage)]
+ assert [result.is_error for result in results] == [False, True]
+ assert "Opened" not in results[0].content[0].text
+ assert results[1].content[0].text in ('[web_search failed: timeout]\nQuery: "open_page https://example.test/notes"', SYNTHETIC_TOOL_RESULT)
+
+
+_RECORDS = {
+ "completed": HostedRecord(status="completed"),
+ "failed": HostedRecord(status="failed", error="timeout"),
+ "pending": HostedRecord(status="pending"),
+}
+
+
[email protected]("statuses", list(itertools.product(_RECORDS, repeat=3)), ids="-".join)
+def test_every_hosted_call_is_one_result_that_shows_its_own_status(statuses):
+ """For every status of a search and two page actions: each call is exactly one result; a completed page action's
+ line appears once, in its own result; a call that did not complete is an error that says so."""
+
+ actions = (
+ HostedAction("search", queries=("q",)),
+ HostedAction("open_page", url="https://a.test/1"),
+ HostedAction("find_in_page", url="https://a.test/2", pattern="x"),
+ )
+ blocks = [
+ _hosted(f"ws_{n}", "web_search", action, _RECORDS[status]) for n, (action, status) in enumerate(zip(actions, statuses))
+ ]
+
+ messages = _transformed(UserMessage((TextBlock("go"),)), _response(*blocks, ANSWER), _follow_up())
+
+ results = [message for message in messages if isinstance(message, ToolResultMessage)]
+ assert [result.tool_call_id for result in results] == ["ws_0", "ws_1", "ws_2"]
+ lines = ("", "Opened https://a.test/1", 'Searched https://a.test/2 for "x"')
+ for result, status, line in zip(results, statuses, lines):
+ text = result.content[0].text
+ assert result.is_error is (status != "completed")
+ if status == "failed":
+ assert text.startswith("[web_search failed: timeout]")
+ elif status == "pending":
+ assert text == SYNTHETIC_TOOL_RESULT
+ if line:
+ assert sum(other.content[0].text.count(line) for other in results) == (1 if status == "completed" else 0)
+ assert (line in text) is (status == "completed")
+
+
+def test_the_posts_an_answer_cites_show_even_when_its_first_x_search_failed():
+ """Every line attached to a result shows whatever its status: the cited posts land on the first X search that was
+ not cut off, and a failed one renders them after its status line."""
+
+ post = HostedSource(url="https://x.com/OpenAI/status/1")
+ failed = _hosted("ctc_0", "x_search", HostedAction("x_search", variant="keyword", query="a"), _RECORDS["failed"])
+ found = _hosted("ctc_1", "x_search", HostedAction("x_search", variant="keyword", query="b"), _RECORDS["completed"])
+
+ messages = _transformed(
+ UserMessage((TextBlock("go"),)),
+ _response(failed, found, ANSWER, summary=HostedSummary(cited_sources=(post,))),
+ _follow_up(),
+ )
+
+ texts = [message.content[0].text for message in messages if isinstance(message, ToolResultMessage)]
+ assert sum(text.count(post.url) for text in texts) == 1
+ assert texts[0].startswith("[x_search failed: timeout]") and post.url in texts[0]
+
+
+def test_a_hosted_call_after_a_client_call_stays_in_place_so_no_split_separates_the_client_call_from_its_result():
+ read = ToolCallBlock(id="toolu_1", name="read", arguments={"path": "a"})
+ after = TextBlock(text="reading it now")
+ response = AssistantMessage(
+ (read, SEARCH, after), XAI, "tool_use", hosted_summary=HostedSummary()
+ )
+
+ messages = _transformed(
+ UserMessage((TextBlock("go"),)),
+ response,
+ ToolResultMessage("toolu_1", "read", (TextBlock("contents"),)),
+ AssistantMessage((TextBlock(text="done"),), XAI, "stop"),
+ _follow_up(),
+ )
+
+ _, sent, result, *_ = messages
+ assert sent.content == (read, TextBlock(text=SEARCH_TEXT), after)
+ assert result.tool_call_id == "toolu_1" and result.content[0].text == "contents"
+ assert not any(
+ isinstance(message, ToolResultMessage) and message.content[0].text == SYNTHETIC_TOOL_RESULT for message in messages
+ )
+
+
[email protected]("form", ["in-flight", "after-a-client-call"])
+def test_the_posts_an_answer_cites_show_on_a_call_kept_in_place(form):
+ post = HostedSource(url="https://x.com/OpenAI/status/1")
+ search = _hosted("ctc_0", "x_search", HostedAction("x_search", variant="keyword", query="a"), _RECORDS["completed"])
+ read = ToolCallBlock(id="toolu_1", name="read", arguments={"path": "a"})
+ content = (search, read) if form == "in-flight" else (read, search)
+ response = AssistantMessage(content, XAI, "tool_use", hosted_summary=HostedSummary(cited_sources=(post,)))
+ later = () if form == "in-flight" else (AssistantMessage((TextBlock(text="done"),), XAI, "stop"), _follow_up())
+
+ messages = _transformed(
+ UserMessage((TextBlock("go"),)), response, ToolResultMessage("toolu_1", "read", (TextBlock("contents"),)), *later
+ )
+
+ in_place = [block.text for block in messages[1].content if isinstance(block, TextBlock)]
+ assert len(in_place) == 1 and in_place[0].endswith("Posts cited in the answer:\n1. https://x.com/OpenAI/status/1")
diff --git a/tests/scenarios/INDEX.yaml b/tests/scenarios/INDEX.yaml
index 0ecbd7294..659fa1853 100644
--- a/tests/scenarios/INDEX.yaml
+++ b/tests/scenarios/INDEX.yaml
@@ -54,6 +54,8 @@ capabilities:
- tests/test_model_hub_capability_evidence.py
- tests/test_provider_overlay.py
- tests/agent_core/ai/test_hosted_requests.py
+ - tests/agent_core/ai/test_hosted_parsing.py
+ - tests/agent_core/ai/test_hosted_transform.py
- tests/test_vibey_agent.py
- tests/test_model_hub_evidence_rules.py
- tests/test_model_hub_admission.py
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index 75efd1856..627046634 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -10,6 +10,8 @@ capability:
- tests/test_model_hub_capability_evidence.py
- tests/test_provider_overlay.py
- tests/agent_core/ai/test_hosted_requests.py
+ - tests/agent_core/ai/test_hosted_parsing.py
+ - tests/agent_core/ai/test_hosted_transform.py
- tests/test_vibey_agent.py
- tests/test_model_hub_evidence_rules.py
- tests/test_model_hub_config.py
@@ -216,6 +218,34 @@ scenarios:
- tests/test_model_hub_reasoning_tiers.py::test_a_persisted_catalog_list_offers_no_client_preset_to_vibey
- tests/test_model_hub_vibey_consumer.py::test_a_released_vibey_row_loads_without_its_client_preset
- tests/test_model_hub_evidence_rules.py::test_a_refused_effort_still_waits_for_a_capable_hop_that_is_cooling_down
+ - id: MH-HOSTED-VIBEY-002
+ name: Every native hosted item becomes one hosted call with a provider-neutral action and its record; citations stay on the text that cites them; the response's counters and reported cost go to its summary
+ status: covered
+ kind: contract
+ layer: contract
+ test: tests/agent_core/ai/test_hosted_parsing.py::test_an_xai_web_search_is_one_hosted_call_with_its_sources_cited_text_and_reported_cost
+ related_tests:
+ - tests/agent_core/ai/test_hosted_parsing.py::test_xai_x_searches_keep_their_variants_and_the_answer_cites_each_post_once
+ - tests/agent_core/ai/test_hosted_parsing.py::test_the_mapping_rule_gives_every_responses_item_a_provider_neutral_action
+ - tests/agent_core/ai/test_hosted_parsing.py::test_no_hosted_call_without_a_native_declaration_or_a_known_serving_source
+ - tests/agent_core/ai/test_hosted_parsing.py::test_an_anthropic_search_and_its_result_are_one_hosted_call_and_the_text_keeps_its_citation
+ - tests/agent_core/ai/test_hosted_parsing.py::test_parallel_anthropic_searches_finalize_by_id_and_a_search_cut_off_stays_pending
+ - tests/agent_core/agent/test_compaction.py::test_a_hosted_call_a_checkpoint_turn_makes_is_recorded_with_its_cost_and_the_checkpoint_holds
+ - id: MH-HOSTED-VIBEY-003
+ name: Each hosted call replays in portable form as exactly one unit, a synthetic same-named call and result or in-place text, written by the one record-to-text function with its own status
+ status: covered
+ kind: contract
+ layer: contract
+ test: tests/test_vibey_agent.py::test_a_native_search_is_kept_as_one_hosted_call_and_replayed_next_turn_as_a_synthetic_call
+ related_tests:
+ - tests/agent_core/ai/test_hosted_transform.py::test_a_replayed_search_is_a_synthetic_same_named_call_and_result_on_every_protocol
+ - tests/agent_core/ai/test_hosted_transform.py::test_every_hosted_call_is_its_own_synthetic_call_and_a_page_action_says_what_it_did
+ - tests/agent_core/ai/test_hosted_transform.py::test_a_failed_or_cut_off_call_never_reads_as_a_successful_empty_result
+ - tests/agent_core/ai/test_hosted_transform.py::test_the_posts_an_x_answer_cites_are_listed_once_in_its_first_x_search_result
+ - tests/agent_core/ai/test_hosted_transform.py::test_a_response_its_turn_still_waits_on_keeps_each_call_in_place_as_text
+ - tests/agent_core/ai/test_hosted_transform.py::test_every_hosted_call_is_one_result_that_shows_its_own_status
+ - tests/agent_core/ai/test_hosted_transform.py::test_the_posts_an_answer_cites_show_on_a_call_kept_in_place
+ - tests/agent_core/agent/test_context.py::test_a_hosted_call_counts_as_the_call_and_result_it_is_replayed_as_never_as_its_opaque_payload
- id: MH-VIBEY-007
name: Vibey starts once with the user's Sources and built-in Agent models, seeded when its first Source exists
status: covered
diff --git a/tests/test_vibey_agent.py b/tests/test_vibey_agent.py
index 5b5248269..0c79e63f9 100644
--- a/tests/test_vibey_agent.py
+++ b/tests/test_vibey_agent.py
@@ -39,6 +39,7 @@ from core.agent_core.ai.provider import Done
from core.agent_core.harness.projection import project
from core.agent_core.messages import (
AssistantMessage,
+ HostedToolBlock,
ImageBlock,
TextBlock,
ThinkingBlock,
@@ -2436,6 +2437,63 @@ async def test_a_hop_resolved_native_hosted_tool_reaches_the_gateway_pinned_to_i
assert harness.controller.im_client.sent == ["hi"]
+async def test_a_native_search_is_kept_as_one_hosted_call_and_replayed_next_turn_as_a_synthetic_call(
+ engine, session, tmp_path, published
+) -> None:
+ """MH-HOSTED-VIBEY-003 (vibey-hosted-tools.md §4.2, §5): the turn's hosted call is committed as one hosted block
+ with its record, and the next turn's request carries it as a same-named call and result with the sources."""
+ import httpx
+
+ from modules.agents.vibey.models import registry_providers
+
+ served = json.dumps(
+ {"provider": "xai", "api": "openai_responses", "model": "grok-4.6", "source": "src_upstream01"},
+ separators=(",", ":"),
+ )
+ call = {
+ "id": "ws_1",
+ "type": "web_search_call",
+ "status": "completed",
+ "action": {"type": "search", "query": "avibe release", "sources": [{"type": "url", "url": "https://avibe.bot/r"}]},
+ }
+ first = (
+ f'data: {json.dumps({"type": "response.output_item.done", "output_index": 0, "item": call})}\n\n'
+ 'data: {"type":"response.output_item.added","output_index":1,"item":{"type":"message","id":"msg_1"}}\n\n'
+ 'data: {"type":"response.output_text.delta","output_index":1,"delta":"found it"}\n\n'
+ 'data: {"type":"response.completed","response":{"status":"completed","output":null}}\n\n'
+ )
+ replies = [first, _TEXT_STREAMS["openai_responses"][1]]
+ seen: list[dict] = []
+
+ def gateway(request: httpx.Request) -> httpx.Response:
+ seen.append(json.loads(request.content))
+ return httpx.Response(
+ 200, headers={"content-type": "text/event-stream", "x-avibe-served-hop": served}, text=replies.pop(0)
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(gateway)) as client:
+ harness = _Harness(
+ engine, tmp_path, "telegram", [], providers=registry_providers(media_loader=None, client=client)
+ )
+ harness.controller.hub_protocol = "openai_responses"
+ harness.controller.hub_hosted_tools = {
+ "web_search": {
+ "mode": "native", "declaration": {"type": "web_search"}, "include": [], "executor": None, "replay": False
+ }
+ }
+ await harness.agent.handle_message(harness.request("search"))
+ committed = (await harness.context_rows())[-1].message
+ await harness.agent.handle_message(harness.request("and then?"))
+
+ (hosted,) = [block for block in committed.content if isinstance(block, HostedToolBlock)]
+ assert (hosted.tool, hosted.record.status, hosted.native.source_id) == ("web_search", "completed", "src_upstream01")
+ assert hosted.native.payload == (call,)
+ replayed = [item for item in seen[1]["input"] if item.get("type") in ("function_call", "function_call_output")]
+ assert [item["type"] for item in replayed] == ["function_call", "function_call_output"]
+ assert json.loads(replayed[0]["arguments"]) == {"query": "avibe release"} and replayed[0]["name"] == "web_search"
+ assert "https://avibe.bot/r" in replayed[1]["output"]
+
+
_NATIVE_SEARCH = {"mode": "native", "declaration": {"type": "web_search"}, "include": [], "executor": None, "replay": False}
_PROXY_IMAGE = {"mode": "proxy", "executor": {"source_id": "src_executor01", "model_id": "gpt-image"}, "replay": False}