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): give each hosted failure Avibe words itself a stable error code, so a display can localize it (#2595)

Call White26081bf881b1
diff --git a/core/agent_core/ai/hosted.py b/core/agent_core/ai/hosted.py
index 99187ee54..300447f13 100644
--- a/core/agent_core/ai/hosted.py
+++ b/core/agent_core/ai/hosted.py
@@ -53,19 +53,25 @@ 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."""
+def failure(reason: Any, code: str | None = None) -> tuple[str, str | None]:
+ """A failed record's ``error`` and ``error_code``: the provider's own words, with no code, or the English reason
+ Avibe wrote for ``code`` (``HOSTED_ERROR_CODES``). The text has any credential redacted and is never longer than
+ the record allows; it is persisted and replayed to later models. A reason that says nothing is
+ ``provider_no_reason``."""
- 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] + "…"
+ message = " ".join(redact_provider_text(reason).split()) if isinstance(reason, str) else ""
+ if not message:
+ return "the provider reported no reason", "provider_no_reason"
+ return (message if len(message) <= HOSTED_ERROR_MAX_CHARS else message[: HOSTED_ERROR_MAX_CHARS - 1] + "…"), code
-def _item_error(item: Mapping[str, Any], status: str) -> str:
+def _item_error(item: Mapping[str, Any], status: str) -> tuple[str, str | None]:
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}")
+ if isinstance(error, str):
+ return failure(error)
+ return failure(f"the provider ended the call {status}", "provider_no_reason")
def _payload(*items: Mapping[str, Any]) -> tuple[dict[str, Any], ...]:
@@ -92,7 +98,7 @@ def responses_hosted_block(
call_id: str,
finished: bool = True,
image: HostedImage | None = None,
- image_error: str | None = None,
+ image_error: tuple[str, str] | None = None,
) -> HostedToolBlock:
"""One Responses hosted-call item (a ``web_search_call``, an ``image_generation_call``, or xAI's X-search
``custom_tool_call``) as its block.
@@ -100,7 +106,7 @@ def responses_hosted_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. A generated image is the file
the adapter saved, ``image``: the item's base64 ``result`` is never kept (§7.3), and a finished call that saved no
- image failed, for ``image_error`` when the adapter knows why.
+ image failed, for ``image_error``, a reason and its code, when the adapter knows why.
"""
tool = responses_hosted_tool(item)
@@ -116,11 +122,12 @@ def responses_hosted_block(
record_status = "completed"
else:
record_status = "pending"
- error = _item_error(item, record_status) if record_status in ("failed", "incomplete") else None
+ error, error_code = _item_error(item, record_status) if record_status in ("failed", "incomplete") else (None, None)
images: tuple[HostedImage, ...] | None = None
if tool == "image_generation":
if record_status == "completed" and image is None:
- record_status, error = "failed", bounded_error(image_error or "the provider returned no image")
+ record_status = "failed"
+ error, error_code = failure(*(image_error or ("the provider returned no image", "provider_no_image")))
images = (image,) if image is not None and record_status == "completed" else ()
action, sources = generate_action(item), ()
# The transcript's copy names the saved file in place of the base64 image.
@@ -135,7 +142,9 @@ def responses_hosted_block(
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, images=images), # type: ignore[arg-type]
+ record=HostedRecord(
+ status=record_status, error=error, sources=sources, images=images, error_code=error_code # type: ignore[arg-type]
+ ),
native=HostedNative(source_id=source_id, payload=_payload(item)),
)
@@ -235,8 +244,9 @@ def anthropic_hosted_block(
),
)
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 ""))
+ # The provider's own error code is its reason, in its words.
+ error, error_code = failure(content.get("error_code") if isinstance(content, Mapping) else None)
+ record = HostedRecord(status="failed", error=error, error_code=error_code)
payload = (use,) if result is None else (use, result)
return HostedToolBlock(
id=str(use["id"]),
diff --git a/core/agent_core/ai/openai_responses.py b/core/agent_core/ai/openai_responses.py
index 62a573888..4964f0dc4 100644
--- a/core/agent_core/ai/openai_responses.py
+++ b/core/agent_core/ai/openai_responses.py
@@ -1644,7 +1644,7 @@ def _add_hosted_call(
finished: bool = True,
backfill: bool = False,
image: HostedImage | None = None,
- image_error: str | None = None,
+ image_error: tuple[str, str] | None = None,
) -> 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.
@@ -1661,7 +1661,7 @@ def _add_hosted_call(
if backfill and current is not None and current.record.status != "pending":
return
if backfill and tool == "image_generation":
- image_error = "the image was not streamed before the response ended"
+ image_error = ("the image was not streamed before the response ended", "image_not_streamed")
assembler.hosted_block(
output_index,
responses_hosted_block(
@@ -1703,8 +1703,11 @@ class _ImageBudget:
return None
-async def _saved_image(sink: MediaSink | None, item: Mapping[str, Any]) -> tuple[HostedImage | None, str | None]:
- """The file a done ``image_generation_call`` was saved to, with its output size, or why there is none (§7.3).
+async def _saved_image(
+ sink: MediaSink | None, item: Mapping[str, Any]
+) -> tuple[HostedImage | None, tuple[str, str] | None]:
+ """The file a done ``image_generation_call`` was saved to, with its output size, or why there is none and its code
+ (§7.3).
Only a completed call's image is saved: that is the only record that lists one, so no file is written that no
record names."""
@@ -1713,11 +1716,11 @@ async def _saved_image(sink: MediaSink | None, item: Mapping[str, Any]) -> tuple
if item.get("status") != "completed" or not isinstance(encoded, str) or not encoded:
return None, None
if sink is None:
- return None, "nothing here can keep a generated image"
+ return None, ("nothing here can keep a generated image", "image_no_store")
try:
image = await sink.save_image(encoded)
except (ValueError, OSError) as error:
- return None, f"the image could not be saved: {error}"
+ return None, (f"the image could not be saved: {error}", "image_not_saved")
width, height = image_dimensions(item.get("size"))
return replace(image, width=width, height=height), None
diff --git a/core/agent_core/messages.py b/core/agent_core/messages.py
index e1f966077..0ff8309f6 100644
--- a/core/agent_core/messages.py
+++ b/core/agent_core/messages.py
@@ -24,12 +24,26 @@ IMAGE_MIME_TYPES: tuple[str, ...] = ("image/png", "image/jpeg", "image/gif", "im
_LARGE_REF_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
_SOURCE_ID_RE = re.compile(r"^src_[a-z0-9]{8,}$")
_COUNTER_NAME_RE = re.compile(r"^[a-z0-9_]{1,64}$")
+_ERROR_CODE_RE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
HostedToolName = Literal["web_search", "x_search", "image_generation"]
HOSTED_TOOLS: tuple[str, ...] = ("web_search", "x_search", "image_generation")
HostedStatus = Literal["completed", "failed", "incomplete", "pending"]
HOSTED_STATUSES: tuple[str, ...] = ("completed", "failed", "incomplete", "pending")
HOSTED_ERROR_MAX_CHARS = 400
+#: The stable code of each hosted failure Avibe words itself (``HostedRecord.error_code``), by which a display localizes
+#: it; a provider's own reason has none. A record loads with any snake_case code, so one a newer build wrote still reads.
+HOSTED_ERROR_CODES: tuple[str, ...] = (
+ "provider_no_reason",
+ "provider_no_image",
+ "image_not_streamed",
+ "image_not_saved",
+ "image_no_store",
+ "executor_no_image",
+ "gateway_unreachable",
+ "gateway_refused",
+ "gateway_no_result",
+)
COST_BASES: tuple[str, ...] = ("reported", "list", "included")
SOURCE_BILLINGS: tuple[str, ...] = ("monthly", "metered")
@@ -323,12 +337,17 @@ class HostedImage:
@dataclass(frozen=True)
class HostedRecord:
- """Per-call facts. ``images`` is set exactly for ``image_generation`` (possibly empty)."""
+ """Per-call facts. ``images`` is set exactly for ``image_generation`` (possibly empty).
+
+ ``error`` is model-facing English. ``error_code`` names a reason Avibe wrote (``HOSTED_ERROR_CODES``), only beside
+ an ``error``.
+ """
status: HostedStatus
error: Optional[str] = None
sources: tuple[HostedSource, ...] = ()
images: Optional[tuple[HostedImage, ...]] = None
+ error_code: Optional[str] = None
def __post_init__(self) -> None:
_require(self.status, str, "hosted status")
@@ -339,6 +358,9 @@ class HostedRecord:
raise ValueError("a hosted error is present exactly for failed and incomplete records")
if self.error is not None and len(self.error) > HOSTED_ERROR_MAX_CHARS:
raise ValueError(f"a hosted error is at most {HOSTED_ERROR_MAX_CHARS} characters")
+ _require(self.error_code, str, "hosted error code", optional=True)
+ if self.error_code is not None and (self.error is None or not _ERROR_CODE_RE.fullmatch(self.error_code)):
+ raise ValueError("a hosted error code is snake_case and comes only with an error")
if not isinstance(self.sources, tuple) or not all(isinstance(s, HostedSource) for s in self.sources):
raise ValueError("hosted sources must be a tuple of HostedSource")
if self.images is not None and (
@@ -671,6 +693,7 @@ def _source_from_dict(data: Any) -> HostedSource:
def _record_to_dict(record: HostedRecord) -> dict[str, Any]:
out: dict[str, Any] = {"status": record.status}
_put(out, "error", record.error)
+ _put(out, "error_code", record.error_code)
out["sources"] = [_source_to_dict(source) for source in record.sources]
if record.images is not None:
images = []
@@ -685,7 +708,7 @@ def _record_to_dict(record: HostedRecord) -> dict[str, Any]:
def _record_from_dict(data: Any) -> HostedRecord:
- f = _read(data, "hosted record", {"status": str, "sources": list}, {"error": str, "images": list})
+ f = _read(data, "hosted record", {"status": str, "sources": list}, {"error": str, "error_code": str, "images": list})
images = None
if "images" in f:
images = tuple(
@@ -699,6 +722,7 @@ def _record_from_dict(data: Any) -> HostedRecord:
error=f.get("error"),
sources=tuple(_source_from_dict(source) for source in f["sources"]),
images=images,
+ error_code=f.get("error_code"),
)
diff --git a/docs/plans/agent-core-contracts/message.schema.json b/docs/plans/agent-core-contracts/message.schema.json
index 8a8645773..38eef516d 100644
--- a/docs/plans/agent-core-contracts/message.schema.json
+++ b/docs/plans/agent-core-contracts/message.schema.json
@@ -898,7 +898,12 @@
"type": "string",
"minLength": 1,
"maxLength": 400,
- "description": "Bounded and redacted."
+ "description": "Bounded and redacted. Model-facing English: the provider's own reason, or one Avibe wrote."
+ },
+ "error_code": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]{0,63}$",
+ "description": "The stable code of a reason Avibe wrote (`HOSTED_ERROR_CODES`), by which a display localizes it; absent for a provider's own reason. A reader accepts any snake_case code."
},
"sources": {
"type": "array",
@@ -914,6 +919,11 @@
}
}
},
+ "dependencies": {
+ "error_code": [
+ "error"
+ ]
+ },
"if": {
"properties": {
"status": {
diff --git a/docs/plans/vibey-hosted-tools.md b/docs/plans/vibey-hosted-tools.md
index 8df682a78..2a61f3bef 100644
--- a/docs/plans/vibey-hosted-tools.md
+++ b/docs/plans/vibey-hosted-tools.md
@@ -585,8 +585,9 @@ Each has a **Re-verify** action with its cost. Unknown shows nothing.
cancel, crash or kill in between leaves a file no row references. Such files are content-addressed, so they never
duplicate, and the per-response image budget bounds them. A startup sweep of the agent media root removes them
(#2588, before the 3.2.1 RC).
- - Avibe-authored failure reasons in a record's `error` are English model-facing text. Their display is localized
- by a stable `error_code` at the display boundary (#2589, before the 3.2.1 RC).
+ - Avibe-authored failure reasons in a record's `error` are English model-facing text. Each carries a stable
+ `error_code` (C-1 `HostedRecord.error_code`, one of `HOSTED_ERROR_CODES`), by which the display boundary localizes
+ it; a provider's own reason carries none and shows as it is (#2589).
- **The user sees the image.** The Workbench renders it inline from the file, and IM attaches it. That is display,
separate from model context.
- **History and replay never contain base64.**
diff --git a/modules/agents/vibey/tools.py b/modules/agents/vibey/tools.py
index b87776dea..739434994 100644
--- a/modules/agents/vibey/tools.py
+++ b/modules/agents/vibey/tools.py
@@ -24,7 +24,7 @@ import httpx
from core.agent_core.agent.models import ModelSelection
from core.agent_core.agent.recovery import RecoveryRenderer
from core.agent_core.ai._common import CONNECT_TIMEOUT_S, auth_headers, join_endpoint_url
-from core.agent_core.ai.hosted import bounded_error, generate_action, image_dimensions, record_text
+from core.agent_core.ai.hosted import failure, generate_action, image_dimensions, record_text
from core.agent_core.ai.provider import HostedExecutor, MediaSink, ModelEndpoint
from core.agent_core.messages import (
HostedImage,
@@ -160,17 +160,17 @@ class HostedTool:
async with httpx.AsyncClient(timeout=timeout, trust_env=False) as client:
response = await client.post(url, json=body, headers=headers)
except httpx.HTTPError as error:
- return _failed(self.spec.name, f"the gateway could not run the call ({type(error).__name__})")
+ reason = f"the gateway could not run the call ({type(error).__name__})"
+ return _failed(self.spec.name, reason, "gateway_unreachable")
if response.status_code != 200:
- return _failed(
- self.spec.name, f"the gateway refused the call (HTTP {response.status_code} {_error_code(response)})"
- )
+ reason = f"the gateway refused the call (HTTP {response.status_code} {_error_code(response)})"
+ return _failed(self.spec.name, reason, "gateway_refused")
try:
# A proxied image's answer carries megabytes of base64: parsed off the controller loop.
answer = await asyncio.to_thread(response.json)
hosted = _hosted_result(self.spec.name, answer)
except (TypeError, ValueError):
- return _failed(self.spec.name, "the gateway answered with no hosted result")
+ return _failed(self.spec.name, "the gateway answered with no hosted result", "gateway_no_result")
if self.spec.name == "image_generation" and hosted.record.status == "completed":
hosted = await self._saved(hosted, answer)
return hosted
@@ -182,31 +182,38 @@ class HostedTool:
generation = answer.get("generation")
generation = generation if isinstance(generation, Mapping) else {}
width, height = image_dimensions(generation.get("size"))
+ images = answer.get("images")
+ if not isinstance(images, list) or not images:
+ failed = _failed_record(self.spec.name, "the executor returned no image", "executor_no_image")
+ return replace(hosted, record=failed)
+ if self.media is None:
+ failed = _failed_record(self.spec.name, "nothing here can keep a generated image", "image_no_store")
+ return replace(hosted, record=failed)
saved: list[HostedImage] = []
try:
- for item in answer.get("images") or ():
+ for item in images:
encoded = item.get("data") if isinstance(item, Mapping) else None
- if not isinstance(encoded, str) or self.media is None:
- raise ValueError("nothing here can keep a generated image")
+ if not isinstance(encoded, str):
+ raise ValueError("the executor's image is not base64 text")
saved.append(replace(await self.media.save_image(encoded), width=width, height=height))
except (ValueError, OSError) as error:
- return replace(hosted, record=_failed_record(self.spec.name, f"the image could not be saved: {error}"))
- if not saved:
- return replace(hosted, record=_failed_record(self.spec.name, "the executor returned no image"))
+ failed = _failed_record(self.spec.name, f"the image could not be saved: {error}", "image_not_saved")
+ return replace(hosted, record=failed)
# The executor's rendered prompt and resolved size and quality: where a native call's block carries them.
return replace(hosted, record=replace(hosted.record, images=tuple(saved)), action=generate_action(generation))
-def _failed_record(tool: str, reason: str) -> HostedRecord:
+def _failed_record(tool: str, reason: str, code: str) -> HostedRecord:
+ error, error_code = failure(reason, code)
return HostedRecord(
- status="failed", error=bounded_error(reason), images=() if tool == "image_generation" else None
+ status="failed", error=error, error_code=error_code, images=() if tool == "image_generation" else None
)
-def _failed(tool: str, reason: str) -> HostedResult:
+def _failed(tool: str, reason: str, code: str) -> HostedResult:
"""A call that never reached an executor: a failed record, and no execution (§4.2)."""
- return HostedResult(record=_failed_record(tool, reason))
+ return HostedResult(record=_failed_record(tool, reason, code))
def _error_code(response: httpx.Response) -> str:
diff --git a/tests/agent_core/ai/test_hosted_images.py b/tests/agent_core/ai/test_hosted_images.py
index 2ff4fbc49..146d78f30 100644
--- a/tests/agent_core/ai/test_hosted_images.py
+++ b/tests/agent_core/ai/test_hosted_images.py
@@ -116,7 +116,7 @@ def _stream(
return _sse(*events)
-async def _generate(body: str, sink: Sink, *, declared: bool = True) -> list[Any]:
+async def _generate(body: str, sink: Sink | None, *, declared: bool = True) -> list[Any]:
routes = {"image_generation": HostedToolRoute("native", None, False, declaration=DECLARATION)} if declared else {}
request = ModelRequest(
endpoint=ModelEndpoint(
@@ -168,26 +168,37 @@ async def test_a_native_image_is_saved_once_from_its_done_item_and_history_holds
@pytest.mark.parametrize(
- ("done", "status", "encoded", "error"),
+ ("done", "status", "encoded", "stored", "error", "code"),
[
- (False, "completed", base64.b64encode(JPEG).decode(), "the image was not streamed before the response ended"),
- (True, "completed", "@@@ not base64 @@@", "the image could not be saved: "),
+ (
+ False,
+ "completed",
+ base64.b64encode(JPEG).decode(),
+ True,
+ "the image was not streamed before the response ended",
+ "image_not_streamed",
+ ),
+ (True, "completed", "@@@ not base64 @@@", True, "the image could not be saved: ", "image_not_saved"),
+ (True, "completed", base64.b64encode(JPEG).decode(), False, "nothing here can keep a generated image", "image_no_store"),
+ (True, "completed", "", True, "the provider returned no image", "provider_no_image"),
# A call the provider did not complete lists no image, so its bytes are never saved: no file without a record.
- (True, "failed", base64.b64encode(JPEG).decode(), "the provider ended the call failed"),
+ (True, "failed", base64.b64encode(JPEG).decode(), True, "the provider ended the call failed", "provider_no_reason"),
],
- ids=["only-in-the-terminal-copy", "unreadable", "failed-with-bytes"],
+ ids=["only-in-the-terminal-copy", "unreadable", "no-store", "no-image", "failed-with-bytes"],
)
async def test_an_image_that_was_not_saved_is_a_failed_call_never_a_completed_one(
- tmp_path, done, status, encoded, error
+ tmp_path, done, status, encoded, stored, error, code
):
- sink = Sink(tmp_path)
+ """#2589: each reason Avibe writes carries its code, by which a display localizes it."""
+
+ sink = Sink(tmp_path) if stored else None
events = await _generate(_stream(encoded, done=done, terminal_copy=encoded, status=status), sink)
(call,) = [block for block in events[-1].message.content if isinstance(block, HostedToolBlock)]
- assert call.record.status == "failed" and call.record.error.startswith(error)
+ assert call.record.status == "failed" and call.record.error.startswith(error) and call.record.error_code == code
assert call.record.images == () and "result" not in call.native.payload[0]
- assert not sink.saved
+ assert sink is None or not sink.saved
async def test_a_six_megabyte_image_streams_under_the_image_line_cap_and_its_record_says_read_cannot_show_it(tmp_path):
diff --git a/tests/agent_core/ai/test_hosted_parsing.py b/tests/agent_core/ai/test_hosted_parsing.py
index 882752d88..cd813b8fc 100644
--- a/tests/agent_core/ai/test_hosted_parsing.py
+++ b/tests/agent_core/ai/test_hosted_parsing.py
@@ -16,7 +16,7 @@ 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.hosted import anthropic_hosted_block, 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
@@ -407,7 +407,7 @@ async def test_parallel_anthropic_searches_finalize_by_id_and_a_search_cut_off_s
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 (first.record.status, first.record.error, first.record.error_code) == ("failed", "max_uses_exceeded", None)
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")
@@ -425,6 +425,48 @@ async def test_parallel_responses_calls_keep_their_output_order_whatever_order_t
assert all(block.record.status == "completed" for block in message.content[:2])
+_SEARCH_USE = {"type": "server_tool_use", "id": "srvtoolu_1", "name": "web_search", "input": {"query": "a"}}
+
+
+ ("block", "reason", "code"),
+ [
+ (
+ lambda: responses_hosted_block(
+ {"id": "ws_1", "type": "web_search_call", "status": "failed", "error": {"message": "upstream timeout"}},
+ source_id=SERVED,
+ call_id="hosted_0",
+ ),
+ "upstream timeout",
+ None,
+ ),
+ (
+ lambda: responses_hosted_block(
+ {"id": "ws_1", "type": "web_search_call", "status": "incomplete"}, source_id=SERVED, call_id="hosted_0"
+ ),
+ "the provider ended the call incomplete",
+ "provider_no_reason",
+ ),
+ (
+ lambda: anthropic_hosted_block(
+ _SEARCH_USE,
+ {"type": "web_search_tool_result", "content": {"type": "web_search_tool_result_error"}},
+ source_id=SERVED,
+ ),
+ "the provider reported no reason",
+ "provider_no_reason",
+ ),
+ ],
+ ids=["responses-reason", "responses-no-reason", "anthropic-no-reason"],
+)
+def test_a_failed_call_keeps_the_providers_reason_uncoded_and_codes_the_one_avibe_writes_for_none(block, reason, code):
+ """#2589: a display localizes a hosted failure by its ``error_code``, and only Avibe's own English reasons have one;
+ the provider's words show as they are."""
+
+ record = block().record
+ assert (record.error, record.error_code) == (reason, code)
+
+
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."""
diff --git a/tests/agent_core/test_hosted_messages.py b/tests/agent_core/test_hosted_messages.py
index 19bd63881..34a856c97 100644
--- a/tests/agent_core/test_hosted_messages.py
+++ b/tests/agent_core/test_hosted_messages.py
@@ -16,6 +16,7 @@ from jsonschema import Draft7Validator
from referencing import Registry, Resource
from core.agent_core.messages import (
+ HOSTED_ERROR_CODES,
AssistantMessage,
Citation,
HostedAction,
@@ -158,9 +159,15 @@ def _produced() -> list:
unexecuted = ToolResultMessage(
tool_call_id="call_9",
tool_name="web_search",
- content=(TextBlock(text="[web_search failed: verify web search on a Source in Models]"),),
+ content=(TextBlock(text="[web_search failed: the gateway could not run the call (ConnectError)]"),),
is_error=True,
- hosted=HostedResult(record=HostedRecord(status="failed", error="no verified executor")),
+ hosted=HostedResult(
+ record=HostedRecord(
+ status="failed",
+ error="the gateway could not run the call (ConnectError)",
+ error_code="gateway_unreachable",
+ )
+ ),
)
return [native_turn, proxy_call, proxied, included, unexecuted]
@@ -237,6 +244,9 @@ VIOLATIONS = {
"error-on-completed": _set(NATIVE, ("content", 0, "record", "error"), "boom"),
"failed-without-error": _without(NATIVE, ("content", 5, "record"), "error"),
"error-too-long": _set(NATIVE, ("content", 1, "record", "error"), "x" * 401),
+ "error-code-without-error": _set(NATIVE, ("content", 0, "record", "error_code"), "image_not_saved"),
+ "error-code-not-snake-case": _set(NATIVE, ("content", 5, "record", "error_code"), "Image Not Saved"),
+ "empty-error-code": _set(NATIVE, ("content", 5, "record", "error_code"), ""),
"unknown-status": _set(NATIVE, ("content", 0, "record", "status"), "done"),
"images-on-web-search": _set(NATIVE, ("content", 0, "record", "images"), []),
"no-images-on-image-generation": _without(NATIVE, ("content", 4, "record"), "images"),
@@ -289,6 +299,15 @@ def test_schema_and_reader_refuse_the_same_hosted_violations(payload):
message_from_dict(payload)
+def test_a_record_with_an_error_code_this_build_does_not_know_still_loads():
+ """#2589: a newer build may add codes; an older one reads the record and shows its English error."""
+
+ newer = _set(NATIVE, ("content", 5, "record", "error_code"), "executor_overloaded")
+ assert "executor_overloaded" not in HOSTED_ERROR_CODES
+ VALIDATOR.validate(newer)
+ assert message_from_dict(newer).content[5].record.error_code == "executor_overloaded"
+
+
def test_a_failed_generate_may_lack_the_revised_prompt():
# Item 28: OpenAI may return a failed image_generation_call with no revised_prompt.
failed = NATIVE["content"][5]
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index 6de53e1bf..05ee7b833 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -291,6 +291,7 @@ scenarios:
- 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/ai/test_hosted_parsing.py::test_a_failed_call_keeps_the_providers_reason_uncoded_and_codes_the_one_avibe_writes_for_none
- 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
@@ -308,7 +309,7 @@ scenarios:
- 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_largest_form_it_can_go_back_in
- id: MH-HOSTED-VIBEY-004
- name: A proxied hosted call runs on the executor bound for the Turn; its record and execution stay on the tool result and the model reads the record as text, a call that reached no executor as a failure
+ name: A proxied hosted call runs on the executor bound for the Turn, every gateway request naming that Turn; its record and execution stay on the tool result and the model reads the record as text, a call that reached no executor as a failure whose reason carries its code
status: covered
kind: contract
layer: contract
@@ -333,6 +334,7 @@ scenarios:
- tests/agent_core/ai/test_hosted_images.py::test_a_six_megabyte_image_streams_under_the_image_line_cap_and_its_record_says_read_cannot_show_it
- tests/agent_core/ai/test_hosted_images.py::test_a_response_that_streams_images_past_its_budget_ends_as_an_error
- tests/test_vibey_agent.py::test_a_generated_image_is_kept_as_an_immutable_file_its_bytes_name_and_type
+ - tests/test_vibey_agent.py::test_a_proxied_image_that_was_not_saved_is_a_failed_call_with_its_code
- 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 57e2e063a..c8cae969e 100644
--- a/tests/test_vibey_agent.py
+++ b/tests/test_vibey_agent.py
@@ -265,6 +265,7 @@ class _Controller:
provider="test-provider",
supports_images=True,
hosted_tools=self.hub_hosted_tools,
+ gateway_request_metadata={"x-avibe-turn-id": turn_id} if turn_id else {},
)
def _native_start(self, context, *, activation_identity=None) -> None:
@@ -2555,7 +2556,7 @@ def _anthropic_reply(*blocks: str, stop_reason: str) -> str:
@pytest.mark.parametrize(
- ("status", "answer", "is_error", "seen"),
+ ("status", "answer", "is_error", "seen", "code"),
[
(
200,
@@ -2570,19 +2571,36 @@ def _anthropic_reply(*blocks: str, stop_reason: str) -> str:
},
False,
"https://avibe.bot/r",
+ None,
),
- (200, {"record": {"status": "failed", "error": "no Source is verified for web search", "sources": []}}, True, "[web_search failed: no Source is verified"),
- (404, {"type": "error", "error": {"type": "not_found", "code": "unknown_tool"}}, True, "HTTP 404 unknown_tool"),
+ # The gateway's own reason: localized where it was written, so it carries no code.
+ (
+ 200,
+ {"record": {"status": "failed", "error": "no Source is verified for web search", "sources": []}},
+ True,
+ "[web_search failed: no Source is verified",
+ None,
+ ),
+ (
+ 404,
+ {"type": "error", "error": {"type": "not_found", "code": "unknown_tool"}},
+ True,
+ "HTTP 404 unknown_tool",
+ "gateway_refused",
+ ),
+ (None, None, True, "the gateway could not run the call (ConnectError)", "gateway_unreachable"),
+ (200, {"answer": "no record"}, True, "the gateway answered with no hosted result", "gateway_no_result"),
],
- ids=["executed", "no-executor", "refused"],
+ ids=["executed", "no-executor", "refused", "unreachable", "no-result"],
)
async def test_a_proxied_hosted_call_runs_on_the_bound_executor_and_keeps_its_record(
- engine, session, tmp_path, published, status, answer, is_error, seen
+ engine, session, tmp_path, published, status, answer, is_error, seen, code
) -> None:
"""MH-HOSTED-VIBEY-004 (vibey-hosted-tools.md §3.4): on a hop that does not run the tool natively, the model calls
the same-named function; Vibey asks the gateway's executor bound for the Turn, keeps the record and execution on
the tool result, and the model reads the record as text. A call that never reached an executor is a failed
- record, never an empty success."""
+ record, never an empty success, and the reason Vibey writes for it carries its code (#2589). Every gateway
+ request, the model's and the executor's, names the Turn (``x-avibe-turn-id``), which binds the executor."""
import httpx
from modules.agents.vibey.models import registry_providers
@@ -2598,10 +2616,14 @@ async def test_a_proxied_hosted_call_runs_on_the_bound_executor_and_keeps_its_re
]
models: list[dict] = []
executed: list[httpx.Request] = []
+ named: list[str | None] = []
def gateway(request: httpx.Request) -> httpx.Response:
+ named.append(request.headers.get("x-avibe-turn-id"))
if request.url.path == "/vibey/v1/hosted-tools/web_search":
executed.append(request)
+ if status is None:
+ raise httpx.ConnectError("connection refused", request=request)
return httpx.Response(status, json=answer)
models.append(json.loads(request.content))
return httpx.Response(
@@ -2618,8 +2640,10 @@ async def test_a_proxied_hosted_call_runs_on_the_bound_executor_and_keeps_its_re
gateway_client=client,
)
harness.controller.hub_hosted_tools = {"web_search": {"mode": "proxy", "executor": _EXECUTOR, "replay": False}}
- await harness.agent.handle_message(harness.request("search"))
+ message = harness.request("search")
+ await harness.agent.handle_message(message)
+ assert len(named) == 3 and set(named) == {_turn(message.context)}
(request,) = executed
assert json.loads(request.content) == {"arguments": {"query": "avibe release"}, "executor": _EXECUTOR}
assert request.headers["authorization"] == "Bearer hub-token"
@@ -2628,6 +2652,7 @@ async def test_a_proxied_hosted_call_runs_on_the_bound_executor_and_keeps_its_re
result = next(row.message for row in await harness.context_rows() if isinstance(row.message, ToolResultMessage))
assert result.is_error is is_error and result.hosted is not None
assert (result.hosted.execution is not None) == (not is_error)
+ assert result.hosted.record.error_code == code
sent = models[1]["messages"][-1]["content"][0]
assert sent["type"] == "tool_result" and seen in json.dumps(sent)
@@ -2700,6 +2725,51 @@ async def test_a_proxied_image_is_saved_through_the_media_sink_and_its_record_na
assert result.content[0].text.startswith('[image_generation: "A lighthouse at dusk"]')
+ ("images", "stored", "error", "code"),
+ [
+ ([], True, "the executor returned no image", "executor_no_image"),
+ ([{"mime": "image/jpeg", "data": "@@@ not base64 @@@"}], True, "the image could not be saved: ", "image_not_saved"),
+ ([{"mime": "image/jpeg", "data": "/9j/4AAQ"}], False, "nothing here can keep a generated image", "image_no_store"),
+ ],
+ ids=["no-image", "unreadable", "no-store"],
+)
+async def test_a_proxied_image_that_was_not_saved_is_a_failed_call_with_its_code(tmp_path, images, stored, error, code):
+ """§7.3, #2589: an executor's completed image call that saved no file is a failed record, never a completed one
+ listing nothing, and the reason Vibey writes for it carries its code, by which a display localizes it."""
+ import httpx
+
+ from core.agent_core.ai.provider import HostedExecutor, ModelEndpoint
+ from core.agent_core.tools.hosted import hosted_tool_spec
+ from modules.agents.vibey.tools import HostedTool
+
+ answer = {
+ "record": {"status": "completed", "sources": []},
+ "execution": {
+ "mode": "proxy",
+ "executor_origin": {"provider": "openai", "api": "openai_responses", "model": "gpt-image"},
+ "executor_source_id": "src_executor01",
+ "executor_billing": "metered",
+ },
+ "images": images,
+ }
+ endpoint = ModelEndpoint("anthropic", "http://hub.invalid/vibey/v1", "claude-opus-5-5", "hub-token")
+ async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _: httpx.Response(200, json=answer))) as client:
+ tool = HostedTool(
+ hosted_tool_spec("image_generation"),
+ HostedExecutor("src_executor01", "gpt-image"),
+ endpoint,
+ client,
+ media=MediaSnapshots(None, tmp_path / "media") if stored else None, # type: ignore[arg-type]
+ )
+ result = await tool.execute({"prompt": "a lighthouse"}, None) # type: ignore[arg-type]
+
+ record = result.hosted.record
+ assert result.is_error and record.status == "failed" and record.images == ()
+ assert record.error.startswith(error) and record.error_code == code
+ assert not (tmp_path / "media").exists() or not any((tmp_path / "media").iterdir())
+
+
_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}