Skip to content

armgit / avibe

Public Imported from GitHub
0

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

feat(model-hub): web search service records, projection and usage (S2a) (#2892)

Call White01fc7b07f257
diff --git a/core/agent_core/messages.py b/core/agent_core/messages.py
index 3f25b3fd5..c0cfdd43d 100644
--- a/core/agent_core/messages.py
+++ b/core/agent_core/messages.py
@@ -35,6 +35,11 @@ HOSTED_RESULT_TOOLS: tuple[str, ...] = (*HOSTED_TOOLS, "image_generate")
EXECUTION_MODES: tuple[str, ...] = ("proxy", "direct")
HostedStatus = Literal["completed", "failed", "incomplete", "pending"]
HOSTED_STATUSES: tuple[str, ...] = ("completed", "failed", "incomplete", "pending")
+HostedAttemptKind = Literal["service", "model"]
+HostedAttemptOutcome = Literal["completed", "failed", "skipped"]
+HOSTED_ATTEMPT_KINDS: tuple[str, ...] = ("service", "model")
+HOSTED_ATTEMPT_OUTCOMES: tuple[str, ...] = ("completed", "failed", "skipped")
+HOSTED_SKIP_REASONS: tuple[str, ...] = ("blocked", "disabled", "cooling", "query_too_long", "unavailable")
HOSTED_ERROR_MAX_CHARS = 400
#: The largest hosted count a summary holds: the largest integer every JSON reader holds exactly. A provider's count
#: past it is no count, and no price or display has to survive one.
@@ -67,6 +72,14 @@ HOSTED_ERROR_CODES: tuple[str, ...] = (
"search_not_run",
"search_failed",
"response_ended_early",
+ "service_key_invalid",
+ "service_balance",
+ "service_limit",
+ "service_unavailable",
+ "service_refused",
+ "service_unreadable",
+ "search_query_too_long",
+ "search_sources_blocked",
)
COST_BASES: tuple[str, ...] = ("reported", "list", "included")
SOURCE_BILLINGS: tuple[str, ...] = ("monthly", "metered")
@@ -373,6 +386,54 @@ def image_deliverable(image: HostedImage) -> bool:
return os.path.isabs(image.path)
+@dataclass(frozen=True)
+class HostedAttempt:
+ """One candidate reached by a search chain, including candidates skipped before a request."""
+
+ source_id: str
+ label: str
+ kind: HostedAttemptKind
+ outcome: HostedAttemptOutcome
+ error_code: Optional[str] = None
+ skipped: Optional[str] = None
+ retry_at: Optional[str] = None
+ needs_action: Optional[str] = None
+ cost: Optional[HostedCost] = None
+ superseded: Optional[bool] = None
+
+ def __post_init__(self) -> None:
+ _require(self.source_id, str, "attempt source id")
+ if not _SOURCE_ID_RE.fullmatch(self.source_id):
+ raise ValueError(f"invalid source id: {self.source_id!r}")
+ _require_text(self.label, "attempt label")
+ if len(self.label) > 64:
+ raise ValueError("attempt label is at most 64 characters")
+ _require(self.kind, str, "attempt kind")
+ if self.kind not in HOSTED_ATTEMPT_KINDS:
+ raise ValueError(f"unknown attempt kind: {self.kind}")
+ _require(self.outcome, str, "attempt outcome")
+ if self.outcome not in HOSTED_ATTEMPT_OUTCOMES:
+ raise ValueError(f"unknown attempt outcome: {self.outcome}")
+ _require(self.error_code, str, "attempt error code", optional=True)
+ if self.error_code is not None and not _ERROR_CODE_RE.fullmatch(self.error_code):
+ raise ValueError("attempt error code is snake_case")
+ _require(self.skipped, str, "attempt skip reason", optional=True)
+ if self.skipped is not None and self.skipped not in HOSTED_SKIP_REASONS:
+ raise ValueError(f"unknown attempt skip reason: {self.skipped}")
+ _require_text(self.retry_at, "attempt retry_at", optional=True)
+ _require_text(self.needs_action, "attempt needs_action", optional=True)
+ _require(self.cost, HostedCost, "attempt cost", optional=True)
+ _require(self.superseded, bool, "attempt superseded", optional=True)
+ if self.outcome == "skipped" and self.skipped is None:
+ raise ValueError("a skipped attempt needs a skip reason")
+ if self.outcome != "skipped" and self.skipped is not None:
+ raise ValueError("only a skipped attempt has a skip reason")
+ if self.skipped != "cooling" and self.retry_at is not None:
+ raise ValueError("only a cooling attempt has retry_at")
+ if self.outcome == "completed" and self.error_code is not None:
+ raise ValueError("a completed attempt has no error code")
+
+
@dataclass(frozen=True)
class HostedRecord:
"""Per-call facts. ``images`` is set exactly for ``image_generate`` (possibly empty).
@@ -389,6 +450,7 @@ class HostedRecord:
sources: tuple[HostedSource, ...] = ()
images: Optional[tuple[HostedImage, ...]] = None
error_code: Optional[str] = None
+ attempts: Optional[tuple[HostedAttempt, ...]] = None
def __post_init__(self) -> None:
_require(self.status, str, "hosted status")
@@ -408,6 +470,10 @@ class HostedRecord:
not isinstance(self.images, tuple) or not all(isinstance(i, HostedImage) for i in self.images)
):
raise ValueError("hosted images must be a tuple of HostedImage")
+ if self.attempts is not None and (
+ not isinstance(self.attempts, tuple) or not all(isinstance(a, HostedAttempt) for a in self.attempts)
+ ):
+ raise ValueError("hosted attempts must be a tuple of HostedAttempt")
def check_tool(self, tool: str) -> None:
if (self.images is not None) != (tool == "image_generate"):
@@ -460,6 +526,7 @@ class HostedCost:
basis: str
usd: Optional[float] = None
+ estimate: Optional[bool] = None
def __post_init__(self) -> None:
_require(self.basis, str, "cost basis")
@@ -473,6 +540,9 @@ class HostedCost:
require_json_value(self.usd, "cost usd")
if self.usd < 0:
raise ValueError("cost usd must not be negative")
+ _require(self.estimate, bool, "cost estimate", optional=True)
+ if self.estimate and self.usd is None:
+ raise ValueError("an estimated cost needs usd")
@dataclass(frozen=True)
@@ -526,7 +596,7 @@ class ProxyExecution:
absent when the call never reached one. ``cost`` is this attempt's own; ``failed_attempts`` lists the earlier
billed ones, and ``core/hosted_activity`` totals them for display."""
- executor_origin: Origin
+ executor_origin: Union[Origin, ServiceExecutorOrigin]
executor_source_id: str
executor_billing: str
cost: Optional[HostedCost] = None
@@ -541,7 +611,8 @@ class ProxyExecution:
isinstance(attempt, FailedAttempt) for attempt in self.failed_attempts
):
raise ValueError("failed attempts must be a tuple of FailedAttempt")
- _require(self.executor_origin, Origin, "executor origin")
+ if not isinstance(self.executor_origin, (Origin, ServiceExecutorOrigin)):
+ raise ValueError("executor origin must be Origin or ServiceExecutorOrigin")
_require(self.executor_source_id, str, "executor source id")
if not _SOURCE_ID_RE.fullmatch(self.executor_source_id):
raise ValueError(f"invalid source id: {self.executor_source_id!r}")
@@ -608,6 +679,24 @@ class Origin:
raise ValueError(f"unknown protocol: {self.api}")
+@dataclass(frozen=True)
+class ServiceExecutorOrigin:
+ """A search service origin, distinct from the four model-wire protocols."""
+
+ provider: str
+ api: Literal["search_api"]
+ model: str
+
+ def __post_init__(self) -> None:
+ _require(self.provider, str, "service origin.provider")
+ _require(self.api, str, "service origin.api")
+ if self.api != "search_api":
+ raise ValueError("service origin api must be search_api")
+ _require(self.model, str, "service origin.model")
+ if not self.provider or not self.model:
+ raise ValueError("a service origin needs a provider and a service id")
+
+
@dataclass(frozen=True)
class Usage:
input_tokens: int = 0
@@ -785,6 +874,8 @@ def _record_to_dict(record: HostedRecord) -> dict[str, Any]:
_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.attempts is not None:
+ out["attempts"] = [_attempt_to_dict(attempt) for attempt in record.attempts]
if record.images is not None:
images = []
for image in record.images:
@@ -798,7 +889,12 @@ 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, "error_code": str, "images": list})
+ f = _read(
+ data,
+ "hosted record",
+ {"status": str, "sources": list},
+ {"error": str, "error_code": str, "images": list, "attempts": list},
+ )
images = None
if "images" in f:
images = tuple(
@@ -813,6 +909,7 @@ def _record_from_dict(data: Any) -> HostedRecord:
sources=tuple(_source_from_dict(source) for source in f["sources"]),
images=images,
error_code=f.get("error_code"),
+ attempts=tuple(_attempt_from_dict(attempt) for attempt in f["attempts"]) if "attempts" in f else None,
)
@@ -835,16 +932,60 @@ def _action_from_dict(data: Any) -> HostedAction:
return HostedAction(**f)
+def _attempt_to_dict(attempt: HostedAttempt) -> dict[str, Any]:
+ out: dict[str, Any] = {
+ "source_id": attempt.source_id,
+ "label": attempt.label,
+ "kind": attempt.kind,
+ "outcome": attempt.outcome,
+ }
+ for name in ("error_code", "skipped", "retry_at", "needs_action"):
+ _put(out, name, getattr(attempt, name))
+ if attempt.cost is not None:
+ out["cost"] = _cost_to_dict(attempt.cost)
+ _put(out, "superseded", attempt.superseded)
+ return out
+
+
+def _attempt_from_dict(data: Any) -> HostedAttempt:
+ f = _read(
+ data,
+ "hosted attempt",
+ {"source_id": str, "label": str, "kind": str, "outcome": str},
+ {
+ "error_code": str,
+ "skipped": str,
+ "retry_at": str,
+ "needs_action": str,
+ "cost": dict,
+ "superseded": bool,
+ },
+ )
+ return HostedAttempt(
+ source_id=f["source_id"],
+ label=f["label"],
+ kind=f["kind"],
+ outcome=f["outcome"],
+ error_code=f.get("error_code"),
+ skipped=f.get("skipped"),
+ retry_at=f.get("retry_at"),
+ needs_action=f.get("needs_action"),
+ cost=_cost_from_dict(f["cost"]) if "cost" in f else None,
+ superseded=f.get("superseded"),
+ )
+
+
def _cost_to_dict(cost: HostedCost) -> dict[str, Any]:
out: dict[str, Any] = {"basis": cost.basis}
_put(out, "usd", cost.usd)
+ _put(out, "estimate", cost.estimate)
return out
def _cost_from_dict(data: Any) -> HostedCost:
if isinstance(data, Mapping) and isinstance(data.get("usd"), int) and not isinstance(data.get("usd"), bool):
data = {**data, "usd": float(data["usd"])}
- return HostedCost(**_read(data, "hosted cost", {"basis": str}, {"usd": float}))
+ return HostedCost(**_read(data, "hosted cost", {"basis": str}, {"usd": float, "estimate": bool}))
def _citation_to_dict(citation: Citation) -> dict[str, Any]:
@@ -960,6 +1101,17 @@ def origin_from_dict(data: Any) -> Origin:
return Origin(**_read(data, "origin", {"provider": str, "api": str, "model": str}))
+def executor_origin_to_dict(origin: Union[Origin, ServiceExecutorOrigin]) -> dict[str, str]:
+ return {"provider": origin.provider, "api": origin.api, "model": origin.model}
+
+
+def executor_origin_from_dict(data: Any) -> Union[Origin, ServiceExecutorOrigin]:
+ fields = _read(data, "executor origin", {"provider": str, "api": str, "model": str})
+ if fields["api"] == "search_api":
+ return ServiceExecutorOrigin(**fields)
+ return Origin(**fields)
+
+
def message_to_dict(message: Message) -> dict[str, Any]:
if isinstance(message, UserMessage):
return {"role": "user", "content": [_block_to_dict(b) for b in message.content]}
@@ -998,11 +1150,7 @@ def message_to_dict(message: Message) -> dict[str, Any]:
if execution is not None:
hosted_result["execution"] = {
"mode": execution.mode,
- "executor_origin": {
- "provider": execution.executor_origin.provider,
- "api": execution.executor_origin.api,
- "model": execution.executor_origin.model,
- },
+ "executor_origin": executor_origin_to_dict(execution.executor_origin),
"executor_source_id": execution.executor_source_id,
"executor_billing": execution.executor_billing,
}
@@ -1097,7 +1245,7 @@ def message_from_dict(data: Mapping[str, Any]) -> Message:
)
)
execution = ProxyExecution(
- executor_origin=origin_from_dict(e["executor_origin"]),
+ executor_origin=executor_origin_from_dict(e["executor_origin"]),
executor_source_id=e["executor_source_id"],
executor_billing=e["executor_billing"],
cost=_cost_from_dict(e["cost"]) if "cost" in e else None,
diff --git a/core/handlers/model_hub/adapter.py b/core/handlers/model_hub/adapter.py
index d1002c869..7c21d1da1 100644
--- a/core/handlers/model_hub/adapter.py
+++ b/core/handlers/model_hub/adapter.py
@@ -1,4 +1,4 @@
-"""Model Hub EngineAdapter interface. FINAL CONTRACT v18 (2026-10-20).
+"""Model Hub EngineAdapter interface. FINAL CONTRACT v19 (2026-10-21).
This file is the canonical adapter boundary and must remain byte-identical to
``core/handlers/model_hub/adapter.py``. The adapter owns one-Source operations:
diff --git a/core/handlers/model_hub/capability_evidence.py b/core/handlers/model_hub/capability_evidence.py
index c2bbad35b..5eecaeae8 100644
--- a/core/handlers/model_hub/capability_evidence.py
+++ b/core/handlers/model_hub/capability_evidence.py
@@ -44,7 +44,7 @@ POSITIVE_REFRESH_SECONDS = 3600
FeatureKind = Literal["effort", "hosted_tool"]
EvidenceStatus = Literal["verified", "unsupported"]
RoutingStatus = Literal["unsupported", "unknown"]
-ExecutionMode = Literal["native", "executor", "direct"]
+ExecutionMode = Literal["native", "executor", "service", "direct"]
HOSTED_TOOL_ASPECTS: Mapping[str, tuple[str, ...]] = {
"web_search": ("call", "replay"),
@@ -52,7 +52,7 @@ HOSTED_TOOL_ASPECTS: Mapping[str, tuple[str, ...]] = {
# An image call is an ordinary tool call and result, so only its call is evidence.
"image_generate": ("call",),
}
-EXECUTION_MODES: frozenset[str] = frozenset({"native", "executor", "direct"})
+EXECUTION_MODES: frozenset[str] = frozenset({"native", "executor", "service", "direct"})
_NAME_RE = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
_DIGEST_RE = re.compile(r"sha256:[0-9a-f]{64}")
diff --git a/core/handlers/model_hub/pricing.py b/core/handlers/model_hub/pricing.py
index f8bb70126..5b075341c 100644
--- a/core/handlers/model_hub/pricing.py
+++ b/core/handlers/model_hub/pricing.py
@@ -477,6 +477,57 @@ def row_cost(row: Mapping[str, Any], price: Optional[ModelPrice]) -> Cost:
)
+@dataclass
+class ServiceCost:
+ """Priced search-service usage of one aggregate (`web-search-services.md` §4.3).
+
+ Two figures that are never added together: the list valuation of the billable
+ requests at the current catalog price, and the vendors' own reported figures.
+ """
+
+ api_cost_usd: float = 0.0
+ reported_usd: float = 0.0
+ # Billable requests whose service the current catalog no longer prices.
+ excluded_requests: int = 0
+ api_cost_lower_bound: bool = False
+
+ def add(self, other: "ServiceCost") -> None:
+ self.api_cost_usd += other.api_cost_usd
+ self.reported_usd += other.reported_usd
+ self.excluded_requests += other.excluded_requests
+ self.api_cost_lower_bound = self.api_cost_lower_bound or other.api_cost_lower_bound
+
+ @property
+ def lower_bound(self) -> bool:
+ # Like an unpriced model's tokens, an unpriced billable request makes the figure a floor.
+ return self.api_cost_lower_bound or self.excluded_requests > 0
+
+ def fields(self) -> dict[str, Any]:
+ return {
+ "reported_usd": round(self.reported_usd, 6),
+ "api_cost_usd": round(self.api_cost_usd, 6),
+ "api_cost_lower_bound": self.lower_bound,
+ }
+
+
+def service_row_cost(row: Mapping[str, Any], usd_per_1k: Optional[float]) -> ServiceCost:
+ """Value one service ledger row at its service's list price; None when the catalog no longer prices it.
+
+ Every billable request is one request at the list price. A request whose
+ billing is unknown adds nothing and makes the figure a floor, as a stored
+ `lower_bound` does; the reported figures ride beside it unchanged.
+ """
+
+ billable = int(row.get("billable_requests") or 0)
+ floor = row.get("lower_bound") is True or int(row.get("uncertain_requests") or 0) > 0
+ reported = float(row.get("reported_usd") or 0.0)
+ if usd_per_1k is None:
+ # The catalog cannot value this service anymore. Even a non-billable
+ # historical request is unpriced; retain that fact as a lower bound.
+ return ServiceCost(reported_usd=reported, excluded_requests=billable, api_cost_lower_bound=True)
+ return ServiceCost(api_cost_usd=billable * usd_per_1k / 1000, reported_usd=reported, api_cost_lower_bound=floor)
+
+
def billing_period(today: date, renewal_day: Optional[int]) -> tuple[str, date, Optional[date]]:
"""(basis, first day, next renewal) of the period ending today."""
diff --git a/core/handlers/model_hub/provenance.py b/core/handlers/model_hub/provenance.py
index 7b002fce5..a560e1502 100644
--- a/core/handlers/model_hub/provenance.py
+++ b/core/handlers/model_hub/provenance.py
@@ -2713,7 +2713,7 @@ class TurnCorrelationRegistry:
self.store.put(
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": normalized_turn_id,
"ts": ts or _utc_now_iso(),
"agent": trace.agent,
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index e6f9347aa..d17c3beb4 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -255,12 +255,13 @@ from .usage import (
USAGE_DEFAULT_WINDOW_DAYS,
USAGE_WINDOW_KEYS,
BoundedUsageLedger,
+ ServiceCatalogEntry,
SourceIdentity,
UsageWriter,
local_usage_day,
)
-CONTRACT_VERSION = 18
+CONTRACT_VERSION = 19
def seeded_source_name(vendor: str) -> str:
@@ -383,8 +384,8 @@ def _described_as_unfit_for_agent_turns(match: Mapping[str, Any]) -> bool:
)
-AGENT_CHAIN_CONTRACT_VERSION = 18
-PROBE_RESULT_CONTRACT_VERSION = 18
+AGENT_CHAIN_CONTRACT_VERSION = 19
+PROBE_RESULT_CONTRACT_VERSION = 19
_SOURCE_DISCOVERY_TIMEOUT_SECONDS = 15
_SOURCE_PROBE_TIMEOUT_SECONDS = 60
# Background inventory refresh. The first tick doubles as the startup delay, so
@@ -1375,7 +1376,7 @@ def _runtime_payload(status: EngineStatus, *, enabled: bool) -> dict:
manager = EngineRuntimeManager()
return {
- "contract_version": 18,
+ "contract_version": 19,
"enabled": enabled,
"host_platform": status.host_platform or manager.host_platform(),
"manifest": manager.contract_manifest(),
@@ -8504,15 +8505,30 @@ class ModelHubService:
)
for source in config.sources
]
+ # The release's search services label and value service rows, as the price
+ # table values model tokens; a row a later catalog dropped stays unpriced.
+ service_catalog = [
+ ServiceCatalogEntry(
+ service_id=entry.search["service_id"],
+ label=entry.label,
+ usd_per_1k=float(entry.search["price"]["usd_per_1k"]),
+ price_date=entry.search["price"]["as_of"],
+ )
+ for entry in api_key_vendor_catalog()
+ if entry.search is not None
+ ]
now = self.now()
prices = self.price_table()
if window is not None:
- return self.usage.report(window=window, now=now, identities=identities, prices=prices)
+ return self.usage.report(
+ window=window, now=now, identities=identities, prices=prices, service_catalog=service_catalog
+ )
return self.usage.summary(
days=USAGE_DEFAULT_WINDOW_DAYS if days is None else days,
now=now,
identities=identities,
prices=prices,
+ service_catalog=service_catalog,
)
async def _fetch_subscription_quota(self, source_id: str, vendor: str, credential_ref: str) -> Mapping[str, Any]:
diff --git a/core/handlers/model_hub/usage.py b/core/handlers/model_hub/usage.py
index 4d6f6dc69..135ff7093 100644
--- a/core/handlers/model_hub/usage.py
+++ b/core/handlers/model_hub/usage.py
@@ -23,6 +23,12 @@ is not ours to cap — so every aggregate here is an exact sum, and
`USAGE_COUNTER_CEILING` constrains only what crosses into the file and back out
of it. A row carrying a counter past it is dropped at whichever door it reaches,
loudly, rather than rewritten into a number nobody spent.
+
+A search-service request reaches no model, so it gets its own row in the same file
+and the same daily and hourly lifecycle: one per Source and catalog `service_id`,
+counting sent requests rather than model calls (`web-search-services.md` §4.3). It
+is told apart by the `service_id` a model row never carries, and a row naming both
+a model and a service is unreadable. Model counters never include it.
"""
from __future__ import annotations
@@ -30,6 +36,7 @@ from __future__ import annotations
import asyncio
import json
import logging
+import math
import queue
import threading
from concurrent.futures import Executor
@@ -41,7 +48,7 @@ from time import monotonic
from typing import Callable, Final, Mapping, Optional, Sequence
from .identifiers import persisted_ledger_key, usage_ledger_key
-from .pricing import Cost, ModelPrice, PriceTable, context_tier_size, row_cost
+from .pricing import Cost, ModelPrice, PriceTable, ServiceCost, context_tier_size, row_cost, service_row_cost
from .state_file import write_state_document
from .stream_wire import ProtocolUsageReport
@@ -165,6 +172,131 @@ def _repair_cache_writes(counters: dict) -> None:
)
+# A service row's counts (`web-search-services.md` §4.3): requests sent, those the
+# catalog's billing rule charges, those whose billing is unknown, and those the
+# vendor priced itself. Every billable request is valued at the request's list
+# price, so no separate list-priced quantity exists. `reported_usd`, the vendor's
+# own figures, rides beside them as an amount rather than a count.
+_SERVICE_COUNTER_KEYS: Final = (
+ "requests",
+ "billable_requests",
+ "uncertain_requests",
+ "reported_requests",
+)
+# What one request's reported cost can be at most: a fixed bound above every catalog
+# version's own per-request ceiling, so a stored figure past it is corruption.
+_SERVICE_REPORTED_USD_CEILING: Final = 1.0
+
+
+def _is_service(value: Mapping) -> bool:
+ """Whether a normalized row, hour slice or counter set counts search requests.
+
+ Every service counter set carries `billable_requests` and no model one does, so
+ the counters themselves say which arithmetic applies wherever they travel.
+ """
+
+ return "billable_requests" in value
+
+
+def _counter_keys(value: Mapping) -> tuple[str, ...]:
+ return _SERVICE_COUNTER_KEYS if _is_service(value) else _COUNTER_KEYS
+
+
+def _amount(value: object) -> Optional[float]:
+ """Read one persisted dollar amount, or None when it is not finite and non-negative."""
+
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ return None
+ try:
+ amount = float(value)
+ except OverflowError:
+ return None
+ if not math.isfinite(amount) or amount < 0:
+ return None
+ return amount
+
+
+def _service_relations_hold(counters: Mapping) -> bool:
+ """The relations a service counter set keeps on every door (§4.3).
+
+ The reported amount is bounded by its count rather than compared for equality
+ anywhere: it is a float sum, so two orders of the same additions may differ in
+ their last place, while each addend's bound survives any order.
+ """
+
+ return (
+ counters["billable_requests"] + counters["uncertain_requests"] <= counters["requests"]
+ and counters["reported_requests"] <= counters["billable_requests"]
+ and counters["reported_usd"] <= counters["reported_requests"] * _SERVICE_REPORTED_USD_CEILING
+ )
+
+
+def _normalize_service_totals(value: object) -> Optional[dict]:
+ """Read strict service counters for a retained slice or pruned history, or None.
+
+ Like a model slice, nested evidence is refused rather than repaired: the daily
+ row is the authoritative aggregate.
+ """
+
+ if not isinstance(value, dict):
+ return None
+ totals: dict = {}
+ for key in _SERVICE_COUNTER_KEYS:
+ counter = value.get(key)
+ if not isinstance(counter, int) or isinstance(counter, bool) or counter < 0:
+ return None
+ if counter > USAGE_COUNTER_CEILING:
+ return None
+ totals[key] = counter
+ amount = _amount(value.get("reported_usd"))
+ if amount is None:
+ return None
+ totals["reported_usd"] = amount
+ return totals if _service_relations_hold(totals) else None
+
+
+def _repair_service_counters(row: Mapping) -> Optional[tuple[dict, bool]]:
+ """Read one daily service row's counts, repaired to their relations (§4.3).
+
+ None when a count is past the ceiling, which makes the row unreadable exactly as
+ it does a model row. A field the row lacks reads as zero. A row that breaks a
+ relation keeps `requests`, has its counts reduced to their bounds and drops the
+ reported quantities that a reduced count no longer covers, or that break their
+ own bound (orphaned dollars included); the second value says so, and the caller
+ marks the row a lower bound.
+ """
+
+ counters: dict = {}
+ broken = False
+ for key in _SERVICE_COUNTER_KEYS:
+ raw = row.get(key, 0)
+ counter = _counter(raw)
+ if counter is None:
+ return None
+ broken = broken or type(raw) is not int or raw < 0
+ counters[key] = counter
+ amount = _amount(row.get("reported_usd", 0.0))
+ billable_reduced = counters["billable_requests"] > counters["requests"]
+ if billable_reduced:
+ counters["billable_requests"] = counters["requests"]
+ broken = True
+ unbilled = counters["requests"] - counters["billable_requests"]
+ if counters["uncertain_requests"] > unbilled:
+ counters["uncertain_requests"] = unbilled
+ broken = True
+ if (
+ billable_reduced
+ or amount is None
+ or counters["reported_requests"] > counters["billable_requests"]
+ or amount > counters["reported_requests"] * _SERVICE_REPORTED_USD_CEILING
+ ):
+ counters["reported_requests"] = 0
+ amount = 0.0
+ broken = True
+ counters["reported_usd"] = amount
+ return counters, broken
+
+
def _utc_now() -> datetime:
return datetime.now(timezone.utc)
@@ -383,17 +515,18 @@ def _has_unresolved_hourly_mass(row: dict) -> bool:
expired = row.get("hourly_expired_totals")
if not isinstance(hours, list):
return True
+ service = _is_service(row)
if expired is None:
- expired = _empty_totals()
+ expired = _empty_totals(service=service)
elif not isinstance(expired, dict):
return True
- known = _empty_totals()
+ known = _empty_totals(service=service)
for item in hours:
if not isinstance(item, dict):
return True
_accumulate(known, item)
_accumulate(known, expired)
- return any(known[key] != row[key] for key in _COUNTER_KEYS)
+ return any(known[key] != row[key] for key in _counter_keys(row))
def _hourly_owner_day_window(
@@ -567,7 +700,7 @@ def _merge_hour_slices(target: dict, incoming: dict) -> None:
target["hourly_history_complete"] = target_complete and incoming_complete
-def _normalize_hour_slice(item: object) -> Optional[dict]:
+def _normalize_hour_slice(item: object, *, service: bool = False) -> Optional[dict]:
"""Normalize one nested hourly slice, or drop it as corrupt."""
if not isinstance(item, dict):
@@ -579,7 +712,7 @@ def _normalize_hour_slice(item: object) -> Optional[dict]:
if parts is None:
return None
key, _start = parts
- counters = _normalize_hourly_totals(item)
+ counters = _normalize_hourly_totals(item, service=service)
if counters is None:
return None
return {
@@ -589,9 +722,11 @@ def _normalize_hour_slice(item: object) -> Optional[dict]:
}
-def _normalize_hourly_totals(value: object) -> Optional[dict]:
+def _normalize_hourly_totals(value: object, *, service: bool = False) -> Optional[dict]:
"""Read strict counters for either a retained slice or pruned history."""
+ if service:
+ return _normalize_service_totals(value)
if not isinstance(value, dict):
return None
if all(key not in value for key in _CACHE_WRITE_KEYS):
@@ -627,6 +762,8 @@ def _normalize_row(row: object) -> Optional[dict]:
if not isinstance(row, dict):
return None
+ if "service_id" in row:
+ return _normalize_service_row(row)
day = _text(row.get("day"))
source_id = persisted_ledger_key(row.get("source_id"))
model_id = persisted_ledger_key(row.get("model_id"))
@@ -668,18 +805,63 @@ def _normalize_row(row: object) -> Optional[dict]:
for subset, superset in _COUNTER_SUBSETS:
normalized[subset] = min(normalized[subset], normalized[superset])
_repair_cache_writes(normalized)
- counters = {key: normalized[key] for key in _COUNTER_KEYS}
normalized["last_metered_at"] = _timestamp(row.get("last_metered_at"))
+ return _normalize_hours(normalized, row)
+
+
+def _normalize_service_row(row: dict) -> Optional[dict]:
+ """Project one persisted search-service row, repaired to its relations, or drop it.
+
+ A row naming both a model and a service is neither; the same day, Source and
+ key rules as a model row apply otherwise.
+ """
+
+ if "model_id" in row:
+ return None
+ day = _text(row.get("day"))
+ source_id = persisted_ledger_key(row.get("source_id"))
+ service_id = persisted_ledger_key(row.get("service_id"))
+ if day is None or source_id is None or service_id is None:
+ return None
+ calendar_day = _calendar_day(day)
+ if calendar_day is None:
+ return None
+ repaired = _repair_service_counters(row)
+ if repaired is None:
+ return None
+ counters, broken = repaired
+ normalized = {
+ "day": calendar_day.isoformat(),
+ "source_id": source_id,
+ "service_id": service_id,
+ **counters,
+ # A broken relation leaves a smaller true statement, so what it values is
+ # a floor; so is a request whose billing is unknown.
+ "lower_bound": row.get("lower_bound") is True or broken or counters["uncertain_requests"] > 0,
+ }
+ if row.get("history_degraded") is True:
+ normalized["history_degraded"] = True
+ normalized["last_metered_at"] = _timestamp(row.get("last_metered_at"))
+ # Repaired counts no longer match the slices that were written beside them,
+ # so where in the day the remainder fell is unknown.
+ return _normalize_hours(normalized, row, invalid=broken)
+
+
+def _normalize_hours(normalized: dict, row: dict, *, invalid: bool = False) -> dict:
+ """Attach a normalized row's optional hourly history, checked against its daily counts."""
+
+ service = _is_service(normalized)
+ counters = {key: normalized[key] for key in _counter_keys(normalized)}
raw_hours = row.get("hours")
if isinstance(raw_hours, list):
# An empty list with the producer's complete flag can be ordinary
# retention expiry: the daily owner outlives its 24-hour slices.
by_key: dict[str, dict] = {}
- invalid_hour = False
+ invalid_hour = invalid
duplicate_hour = False
over_capacity = False
for item in raw_hours:
- normalized_hour = _normalize_hour_slice(item)
+ normalized_hour = _normalize_hour_slice(item, service=service)
if normalized_hour is None:
invalid_hour = True
continue
@@ -703,10 +885,10 @@ def _normalize_row(row: object) -> Optional[dict]:
hours = []
else:
hours = list(by_key.values())
- nested_totals = _empty_totals()
+ nested_totals = _empty_totals(service=service)
for item in hours:
_accumulate(nested_totals, item)
- if any(nested_totals[key] > counters[key] for key in _COUNTER_KEYS):
+ if any(nested_totals[key] > counters[key] for key in counters):
# The daily row is the authoritative released aggregate. A nested
# corruption that exceeds it cannot be repaired by clamping one
# arbitrary hour, so discard all hourly slices and report the
@@ -718,7 +900,7 @@ def _normalize_row(row: object) -> Optional[dict]:
row.get("hourly_history_complete") is True and not invalid_hour
)
normalized["hourly_expired_totals"] = _normalize_hourly_totals(
- row.get("hourly_expired_totals")
+ row.get("hourly_expired_totals"), service=service
)
expiry = _hour_key_parts(row.get("hourly_expired_before"))
normalized["hourly_expired_before"] = expiry[0] if expiry else None
@@ -758,6 +940,54 @@ class SourceIdentity:
model_ids: Sequence[str] = ()
+@dataclass(frozen=True)
+class ServiceCatalogEntry:
+ """One search service as the current catalog lists it, for labelling and valuing its rows.
+
+ Caller-owned for the same reason a Source's label is: the catalog belongs to the
+ release, not to the file, so a row a later catalog no longer lists stays
+ readable, with no label and no price, instead of being priced from a stored copy.
+ """
+
+ service_id: str
+ label: str
+ usd_per_1k: float
+ # The date the catalog's price was verified (`price.as_of`).
+ price_date: str
+
+
+def _keyed_catalog(catalog: Optional[Sequence[ServiceCatalogEntry]]) -> dict[str, ServiceCatalogEntry]:
+ """Key the catalog the way the service rows it values were keyed."""
+
+ keyed: dict[str, ServiceCatalogEntry] = {}
+ for entry in catalog or ():
+ key = usage_ledger_key(entry.service_id)
+ if key is not None:
+ keyed[key] = entry
+ return keyed
+
+
+def _service_price(row: Mapping, keyed_catalog: Mapping[str, ServiceCatalogEntry]) -> Optional[float]:
+ entry = keyed_catalog.get(row["service_id"])
+ return entry.usd_per_1k if entry is not None else None
+
+
+def _service_fields(target: dict, cost: Optional[ServiceCost], *, degraded: bool) -> dict:
+ """A service aggregate's counts, plus its cost fields exactly when the report is priced.
+
+ The ledger keeps the reported amount regardless; publishing it is the cost
+ presence rule's, so an unpriced report carries counts only.
+ """
+
+ published = {key: value for key, value in target.items() if key != "reported_usd"}
+ if cost is None:
+ return published
+ fields = cost.fields()
+ # A degraded read lost rows of unknown size, so no figure from it is exact.
+ fields["api_cost_lower_bound"] = fields["api_cost_lower_bound"] or degraded
+ return {**published, **fields}
+
+
@dataclass(frozen=True)
class _LedgerRead:
rows: list[dict]
@@ -807,17 +1037,39 @@ def _bucket_rows(
prices: Optional[PriceTable],
keyed_model_labels: Mapping[tuple[str, str], str],
*,
+ keyed_catalog: Optional[Mapping[str, ServiceCatalogEntry]] = None,
degraded: bool = False,
) -> list[dict]:
"""Publish one bucket's rows: one per Source and model, summed across context tiers.
Each row is valued at its own tier before the sum, because a tier's rates
- apply only to the calls recorded in it.
+ apply only to the calls recorded in it. Search-service rows follow, one per
+ Source and service, in their own `kind: "service"` shape: a service is never
+ dressed as a model.
"""
published: dict[tuple[str, str], dict] = {}
costs: dict[tuple[str, str], Cost] = {}
+ services: dict[tuple[str, str], dict] = {}
+ service_costs: dict[tuple[str, str], ServiceCost] = {}
for row in rows:
+ if _is_service(row):
+ key = (row["source_id"], row["service_id"])
+ target = services.setdefault(
+ key,
+ {
+ "kind": "service",
+ "source_id": row["source_id"],
+ "service_id": row["service_id"],
+ **_empty_totals(service=True),
+ },
+ )
+ _accumulate(target, row)
+ if prices is not None:
+ service_costs.setdefault(key, ServiceCost()).add(
+ service_row_cost(row, _service_price(row, keyed_catalog or {}))
+ )
+ continue
key = (row["source_id"], row["model_id"])
target = published.setdefault(
key, {"source_id": row["source_id"], "model_id": row["model_id"], **_empty_totals()}
@@ -825,15 +1077,19 @@ def _bucket_rows(
_accumulate(target, row)
if prices is not None:
costs.setdefault(key, Cost()).add(row_cost(row, _row_price(row, prices, keyed_model_labels)))
+ service_rows = [
+ _service_fields(services[key], service_costs.get(key), degraded=degraded)
+ for key in sorted(services)
+ ]
if prices is None:
- return [published[key] for key in sorted(published)]
+ return [published[key] for key in sorted(published)] + service_rows
priced = []
for key in sorted(published):
cost = costs[key]
# A degraded read lost rows of unknown size, so no figure from it is exact.
cost.api_cost_lower_bound = cost.api_cost_lower_bound or degraded
priced.append({**published[key], **cost.fields()})
- return priced
+ return priced + service_rows
def _recency(
@@ -900,13 +1156,21 @@ def _cache_write_increment(usage: Optional[ProtocolUsageReport]) -> dict[str, in
}
-def _row_key(row: dict) -> tuple[str, str, str, int]:
- """A row is one day of one model on one Source, in one context tier."""
+def _row_key(row: dict) -> tuple[str, str, str, int, bool]:
+ """A row is one day of one model on one Source, in one context tier.
- return (row["day"], row["source_id"], row["model_id"], row.get("context_tier", 0))
+ Or of one search service on one Source. The last element keeps the two apart,
+ so a model whose ID spells a catalog service id is never folded into it.
+ """
+
+ if _is_service(row):
+ return (row["day"], row["source_id"], row["service_id"], 0, True)
+ return (row["day"], row["source_id"], row["model_id"], row.get("context_tier", 0), False)
-def _empty_totals() -> dict:
+def _empty_totals(*, service: bool = False) -> dict:
+ if service:
+ return {**{key: 0 for key in _SERVICE_COUNTER_KEYS}, "reported_usd": 0.0}
return {key: 0 for key in _COUNTER_KEYS}
@@ -930,8 +1194,14 @@ def _accumulate(target: dict, row: dict) -> None:
reduced to keep a row writable.
"""
- for key in _COUNTER_KEYS:
+ for key in _counter_keys(target):
target[key] += row[key]
+ if _is_service(target):
+ # A float sum, so it is bounded by its count rather than compared exactly;
+ # see `_service_relations_hold`.
+ target["reported_usd"] += row["reported_usd"]
+ if "lower_bound" in target:
+ target["lower_bound"] = target["lower_bound"] or row.get("lower_bound") is True
def _newer_timestamp(current: Optional[str], candidate: Optional[str]) -> Optional[str]:
@@ -1028,13 +1298,15 @@ def _retain_hour_slices(row: dict, measured: datetime) -> dict:
if not incomplete and (row_day_overlaps or retained or expired_known):
# Compare durable UTC slices even when a host timezone change makes the
# persisted local owner day fall outside the current display grid.
- nested_totals = _empty_totals()
+ nested_totals = _empty_totals(service=_is_service(row))
for item in retained.values():
_accumulate(nested_totals, item)
if expired_known:
_accumulate(nested_totals, expired)
+ # Counts reconcile exactly; a reported amount is a float sum whose order
+ # differs between the day and its hours, so it is bounded, never compared.
if not expired_known or any(
- nested_totals[key] != row[key] for key in _COUNTER_KEYS
+ nested_totals[key] != row[key] for key in _counter_keys(row)
):
logger.warning(
"Model Hub usage ledger row %s cannot reconcile its complete "
@@ -1075,6 +1347,77 @@ def _has_recent_hourly_evidence(row: dict, start: datetime, end: datetime) -> bo
return False
+def _model_increment(
+ call: "UsageCall", source_key: str, *, owner_day: str, metered_at: datetime
+) -> Optional[dict]:
+ """One metered model call as an unnormalized row, or None when its model has no key."""
+
+ model_key = usage_ledger_key(call.model_id)
+ if model_key is None:
+ return None
+ usage = call.usage
+ return {
+ "day": owner_day,
+ "source_id": source_key,
+ "model_id": model_key,
+ "context_tier": call.context_tier,
+ "requests": call.requests,
+ "token_reports": call.requests if usage is not None else 0,
+ "input_tokens": usage.input_tokens if usage else 0,
+ "cached_input_tokens": usage.cached_input_tokens if usage else 0,
+ "output_tokens": usage.output_tokens if usage else 0,
+ **_cache_write_increment(usage),
+ "last_metered_at": metered_at.isoformat(),
+ "hours": [
+ {
+ "key": _hour_key(metered_at),
+ "requests": call.requests,
+ "token_reports": call.requests if usage is not None else 0,
+ "input_tokens": usage.input_tokens if usage else 0,
+ "cached_input_tokens": usage.cached_input_tokens if usage else 0,
+ "output_tokens": usage.output_tokens if usage else 0,
+ **_cache_write_increment(usage),
+ "last_metered_at": metered_at.isoformat(),
+ }
+ ],
+ "hourly_expired_totals": _empty_totals(),
+ "hourly_history_complete": True,
+ }
+
+
+def _service_increment(
+ call: "ServiceUsageCall", source_key: str, *, owner_day: str, metered_at: datetime
+) -> Optional[dict]:
+ """Sent search requests as an unnormalized row, or None when the service has no key.
+
+ It meets the same repair a persisted row does, so a call whose counts break a
+ relation is recorded as the floor that repair leaves, never as written.
+ """
+
+ service_key = usage_ledger_key(call.service_id)
+ if service_key is None:
+ return None
+ counts = {
+ "requests": call.requests,
+ "billable_requests": call.billable_requests,
+ "uncertain_requests": call.uncertain_requests,
+ "reported_requests": call.reported_requests,
+ "reported_usd": call.reported_usd,
+ }
+ return {
+ "day": owner_day,
+ "source_id": source_key,
+ "service_id": service_key,
+ **counts,
+ "last_metered_at": metered_at.isoformat(),
+ "hours": [
+ {"key": _hour_key(metered_at), **counts, "last_metered_at": metered_at.isoformat()}
+ ],
+ "hourly_expired_totals": _empty_totals(service=True),
+ "hourly_history_complete": True,
+ }
+
+
class BoundedUsageLedger:
"""Persist metered upstream-call token counts as a bounded daily aggregate."""
@@ -1166,7 +1509,7 @@ class BoundedUsageLedger:
row.get("history_degraded") is True for row in rows.values()
)
for row in rows.values():
- if all(row[key] <= USAGE_COUNTER_CEILING for key in _COUNTER_KEYS):
+ if all(row[key] <= USAGE_COUNTER_CEILING for key in _counter_keys(row)):
held.append(row)
continue
degraded = True
@@ -1200,7 +1543,7 @@ class BoundedUsageLedger:
holdable: list[dict] = []
for row in rows:
- if all(row[key] <= USAGE_COUNTER_CEILING for key in _COUNTER_KEYS):
+ if all(row[key] <= USAGE_COUNTER_CEILING for key in _counter_keys(row)):
holdable.append(_retain_hour_slices(row, measured))
continue
logger.warning(
@@ -1249,7 +1592,7 @@ class BoundedUsageLedger:
self.record_many((UsageCall(source_id=source_id, model_id=model_id, usage=usage, at=at),))
- def record_many(self, calls: Sequence["UsageCall"]) -> None:
+ def record_many(self, calls: Sequence["UsageCall | ServiceUsageCall"]) -> None:
"""Fold a batch of metered calls into their days' rows in one transaction.
The batch is the reason a backlog cannot grow: one read, one retention
@@ -1290,43 +1633,17 @@ class BoundedUsageLedger:
if _aware(call.at) > persisted_at
else call.owner_day
)
- usage = call.usage
# A live call carries identities, not keys, and this is the one place
# they become one: derive here and every row downstream — new,
# accumulated, or read back next restart — is already a key, so no
# later surface can re-derive one that was folded and orphan its row.
source_key = usage_ledger_key(call.source_id)
- model_key = usage_ledger_key(call.model_id)
increment = None
- if source_key is not None and model_key is not None:
+ if source_key is not None:
increment = _normalize_row(
- {
- "day": owner_day,
- "source_id": source_key,
- "model_id": model_key,
- "context_tier": call.context_tier,
- "requests": call.requests,
- "token_reports": call.requests if usage is not None else 0,
- "input_tokens": usage.input_tokens if usage else 0,
- "cached_input_tokens": usage.cached_input_tokens if usage else 0,
- "output_tokens": usage.output_tokens if usage else 0,
- **_cache_write_increment(usage),
- "last_metered_at": metered_at.isoformat(),
- "hours": [
- {
- "key": _hour_key(metered_at),
- "requests": call.requests,
- "token_reports": call.requests if usage is not None else 0,
- "input_tokens": usage.input_tokens if usage else 0,
- "cached_input_tokens": usage.cached_input_tokens if usage else 0,
- "output_tokens": usage.output_tokens if usage else 0,
- **_cache_write_increment(usage),
- "last_metered_at": metered_at.isoformat(),
- }
- ],
- "hourly_expired_totals": _empty_totals(),
- "hourly_history_complete": True,
- }
+ _service_increment(call, source_key, owner_day=owner_day, metered_at=metered_at)
+ if isinstance(call, ServiceUsageCall)
+ else _model_increment(call, source_key, owner_day=owner_day, metered_at=metered_at)
)
if increment is None:
# Reachable only for a value no config can hold — not text, or
@@ -1460,7 +1777,8 @@ class BoundedUsageLedger:
costs: dict[str, dict[str, Cost]] = {}
for row in rows:
source_id = keyed_sources.get(row["source_id"])
- if source_id is None:
+ if source_id is None or _is_service(row):
+ # A search request is not a model call a plan's quota covers.
continue
cost = row_cost(row, _row_price(row, prices, keyed_model_labels))
costs.setdefault(source_id, {}).setdefault(row["day"], Cost()).add(cost)
@@ -1533,6 +1851,7 @@ class BoundedUsageLedger:
now: datetime,
identities: Optional[Sequence[SourceIdentity]] = None,
prices: Optional[PriceTable] = None,
+ service_catalog: Optional[Sequence[ServiceCatalogEntry]] = None,
) -> dict:
"""Aggregate the window into the read shape the settings page consumes.
@@ -1554,6 +1873,9 @@ class BoundedUsageLedger:
A model's label is its own identity, which only matters for a folded row.
There the key is a head plus a digest, so a tab drawing `model_id` would
show a string nobody typed; the label carries the identity back.
+
+ `service_catalog` is the current release's search services, which label and
+ value service rows the way the price table values model tokens.
"""
bounded_days = max(1, min(int(days), self.retention_days))
@@ -1566,6 +1888,7 @@ class BoundedUsageLedger:
to_day=today.isoformat(),
identities=identities,
prices=prices,
+ service_catalog=service_catalog,
degraded=degraded,
)
@@ -1578,6 +1901,7 @@ class BoundedUsageLedger:
to_day: str,
identities: Optional[Sequence[SourceIdentity]],
prices: Optional[PriceTable] = None,
+ service_catalog: Optional[Sequence[ServiceCatalogEntry]] = None,
degraded: bool = False,
) -> dict:
"""Aggregate one exact set of daily or hourly rows.
@@ -1585,27 +1909,75 @@ class BoundedUsageLedger:
With a price table, every aggregate also carries its API-price valuation,
summed from the same rows so a total always equals the sum of its parts.
A `degraded` read lost rows of unknown size, so every valuation is a floor.
+
+ Search-service rows never enter a model count or `sources[]`: they are
+ `services[]`, and only their valuation joins the totals and days, beside
+ the vendors' own reported figures (`web-search-services.md` §4.3).
"""
keyed_source_labels, keyed_model_labels = _keyed_identities(identities)
+ keyed_catalog = _keyed_catalog(service_catalog)
costs: dict[int, Cost] = {}
+ service_costs: dict[int, ServiceCost] = {}
def priced(target: dict, cost: Optional[Cost]) -> None:
if cost is not None:
costs.setdefault(id(target), Cost()).add(cost)
- def with_cost(target: dict, *, omit: str = "") -> dict:
+ def service_priced(target: dict, cost: Optional[ServiceCost]) -> None:
+ if cost is not None:
+ service_costs.setdefault(id(target), ServiceCost()).add(cost)
+
+ def with_cost(target: dict, *, omit: str = "", with_services: bool = False) -> dict:
published = {key: value for key, value in target.items() if key != omit}
if prices is None:
return published
cost = costs.get(id(target), Cost())
cost.api_cost_lower_bound = cost.api_cost_lower_bound or degraded
- return {**published, **cost.fields()}
+ fields = cost.fields()
+ if with_services:
+ # The services' list valuation joins the one API-price figure;
+ # their reported costs stay beside it, never added to it.
+ service = service_costs.get(id(target), ServiceCost())
+ fields["api_cost_usd"] = round(cost.api_cost_usd + service.api_cost_usd, 6)
+ fields["api_cost_lower_bound"] = fields["api_cost_lower_bound"] or service.lower_bound
+ fields["excluded_service_requests"] = service.excluded_requests
+ fields["service_reported_usd"] = round(service.reported_usd, 6)
+ return {**published, **fields}
totals = _empty_totals()
sources: dict[str, dict] = {}
+ services: dict[tuple[str, str], dict] = {}
by_day: dict[str, dict] = {}
for row in rows:
+ if _is_service(row):
+ entry = keyed_catalog.get(row["service_id"])
+ service_cost = (
+ None
+ if prices is None
+ else service_row_cost(row, entry.usd_per_1k if entry is not None else None)
+ )
+ service_priced(totals, service_cost)
+ day = by_day.setdefault(row["day"], {"day": row["day"], **_empty_totals()})
+ service_priced(day, service_cost)
+ service = services.setdefault(
+ (row["source_id"], row["service_id"]),
+ {
+ "source_id": row["source_id"],
+ "service_id": row["service_id"],
+ "label": keyed_source_labels.get(row["source_id"]),
+ "service_label": entry.label if entry is not None else None,
+ **_empty_totals(service=True),
+ "last_metered_at": None,
+ },
+ )
+ _accumulate(service, row)
+ service_priced(service, service_cost)
+ service["last_metered_at"] = _newer_timestamp(
+ service["last_metered_at"],
+ row["last_metered_at"],
+ )
+ continue
_accumulate(totals, row)
cost = (
None
@@ -1647,11 +2019,22 @@ class BoundedUsageLedger:
_accumulate(day, row)
priced(day, cost)
+ published_services = []
+ for key in sorted(services, key=lambda key: (-services[key]["requests"], key)):
+ service = services[key]
+ fields = _service_fields(
+ service,
+ service_costs.get(id(service), ServiceCost()) if prices is not None else None,
+ degraded=degraded,
+ )
+ if prices is not None:
+ fields["priced"] = service["service_id"] in keyed_catalog
+ published_services.append(fields)
summary = {
"window_days": window_days,
"from_day": from_day,
"to_day": to_day,
- "totals": with_cost(totals),
+ "totals": with_cost(totals, with_services=True),
"sources": [
{
**with_cost(source, omit="models"),
@@ -1668,10 +2051,20 @@ class BoundedUsageLedger:
key=lambda source: (-source["requests"], source["source_id"]),
)
],
- "days": [with_cost(by_day[day]) for day in sorted(by_day)],
+ "services": published_services,
+ "days": [with_cost(by_day[day], with_services=True) for day in sorted(by_day)],
}
if prices is not None:
summary["pricing"] = prices.fields()
+ price_dates = [
+ keyed_catalog[service["service_id"]].price_date
+ for service in published_services
+ if service["service_id"] in keyed_catalog
+ ]
+ if price_dates:
+ # The catalog prices that valued `services[]`, by when the oldest of
+ # them was verified; with no service valued there is nothing to date.
+ summary["pricing"]["service_price_date"] = min(price_dates)
return summary
def report(
@@ -1681,13 +2074,16 @@ class BoundedUsageLedger:
now: datetime,
identities: Optional[Sequence[SourceIdentity]] = None,
prices: Optional[PriceTable] = None,
+ service_catalog: Optional[Sequence[ServiceCatalogEntry]] = None,
) -> dict:
"""Build one modern dense report without reallocating daily history."""
if window not in USAGE_WINDOW_KEYS:
raise ValueError(f"unsupported usage window: {window!r}")
if window == "24h":
- return self._hourly_report(now=now, identities=identities, prices=prices)
+ return self._hourly_report(
+ now=now, identities=identities, prices=prices, service_catalog=service_catalog
+ )
days = int(window[:-1])
bounded_days = max(1, min(days, self.retention_days))
report_local = _local(now)
@@ -1701,9 +2097,11 @@ class BoundedUsageLedger:
to_day=today.isoformat(),
identities=identities,
prices=prices,
+ service_catalog=service_catalog,
degraded=read_degraded,
)
_source_labels, keyed_model_labels = _keyed_identities(identities)
+ keyed_catalog = _keyed_catalog(service_catalog)
by_day = {
row["day"]: []
for row in rows
@@ -1731,6 +2129,7 @@ class BoundedUsageLedger:
by_day.get(bucket_day.isoformat(), []),
prices,
keyed_model_labels,
+ keyed_catalog=keyed_catalog,
degraded=read_degraded,
),
}
@@ -1750,10 +2149,12 @@ class BoundedUsageLedger:
now: datetime,
identities: Optional[Sequence[SourceIdentity]],
prices: Optional[PriceTable] = None,
+ service_catalog: Optional[Sequence[ServiceCatalogEntry]] = None,
) -> dict:
"""Project only measured nested slices onto 24 actual consecutive hours."""
_source_labels, keyed_model_labels = _keyed_identities(identities)
+ keyed_catalog = _keyed_catalog(service_catalog)
report_instant = _aware(now)
starts = _hour_starts(now)
@@ -1818,16 +2219,19 @@ class BoundedUsageLedger:
projected = measured_by_bucket[index].get(key)
if projected is None:
start_local = start.astimezone()
+ service = _is_service(row)
projected = {
"day": start_local.date().isoformat(),
"source_id": row["source_id"],
- "model_id": row["model_id"],
+ **({"service_id": row["service_id"]} if service else {"model_id": row["model_id"]}),
**({"context_tier": row["context_tier"]} if "context_tier" in row else {}),
- **{counter: 0 for counter in _COUNTER_KEYS},
+ **_empty_totals(service=service),
"last_metered_at": None,
}
measured_by_bucket[index][key] = projected
_accumulate(projected, item)
+ if _is_service(row) and row.get("lower_bound") and row.get("uncertain_requests", 0) == 0:
+ projected["lower_bound"] = True
projected["last_metered_at"] = _newer_timestamp(
projected["last_metered_at"],
item.get("last_metered_at"),
@@ -1843,6 +2247,7 @@ class BoundedUsageLedger:
list(measured_by_bucket[index].values()),
prices,
keyed_model_labels,
+ keyed_catalog=keyed_catalog,
# An incomplete hour holds usage it cannot place, so its cost is a floor.
degraded=index in incomplete,
)
@@ -1868,6 +2273,7 @@ class BoundedUsageLedger:
to_day=days[-1],
identities=identities,
prices=prices,
+ service_catalog=service_catalog,
degraded=bool(incomplete),
)
return {
@@ -2041,11 +2447,108 @@ class UsageCall:
)
+@dataclass(frozen=True)
+class ServiceUsageCall:
+ """Sent search-service requests, in the shape the ledger folds them in.
+
+ The service counterpart of `UsageCall`: a request reaches no model, so it is
+ counted by what the catalog's billing rule makes of it (`web-search-services.md`
+ §4.3) rather than by tokens. `requests` is how many sent requests this value
+ speaks for; the other counts are the subsets the relations bound. A request
+ that failed before it was sent is never one of them.
+ """
+
+ source_id: str
+ service_id: str
+ at: datetime
+ requests: int = 1
+ billable_requests: int = 0
+ uncertain_requests: int = 0
+ reported_requests: int = 0
+ reported_usd: float = 0.0
+ owner_day: str = ""
+
+ def __post_init__(self) -> None:
+ if not self.owner_day:
+ object.__setattr__(self, "owner_day", local_usage_day(self.at).isoformat())
+
+ @property
+ def fold_key(self) -> tuple[str, str, str, str, str]:
+ """What makes two calls one daily row and one hourly slice; never a model's key."""
+
+ return ("service", self.owner_day, _hour_key(self.at), self.source_id, self.service_id)
+
+ def folded_with(self, other: "ServiceUsageCall") -> "ServiceUsageCall":
+ """Fold a call that shares this one's row: every count adds, the later stamp wins."""
+
+ return replace(
+ self,
+ at=max(_aware(self.at), _aware(other.at)),
+ requests=self.requests + other.requests,
+ billable_requests=self.billable_requests + other.billable_requests,
+ uncertain_requests=self.uncertain_requests + other.uncertain_requests,
+ reported_requests=self.reported_requests + other.reported_requests,
+ reported_usd=self.reported_usd + other.reported_usd,
+ )
+
+
+def _flag_count(flag: object) -> Optional[int]:
+ """One request's count for a billing flag; None for an answer that is not a flag.
+
+ Anything but a bool, an int included, is refused rather than coerced: `int()`
+ would read 2 as two requests and fail on text. A refused count keeps the call
+ out of the fold, and the ledger repairs it into a floor that keeps the request.
+ """
+
+ if flag is True:
+ return 1
+ if flag is False:
+ return 0
+ return None
+
+
+def _service_call_is_foldable(call: ServiceUsageCall) -> bool:
+ """Only fold service calls whose own counters already satisfy the relations.
+
+ Invalid calls must reach ``_normalize_row`` separately: folding an invalid
+ reported amount with a valid call could make the combined row look valid and
+ erase the required lower-bound witness.
+ """
+
+ counters = {
+ "requests": call.requests,
+ "billable_requests": call.billable_requests,
+ "uncertain_requests": call.uncertain_requests,
+ "reported_requests": call.reported_requests,
+ }
+ if any(
+ type(value) is not int or value < 0 or value > USAGE_COUNTER_CEILING
+ for value in counters.values()
+ ):
+ return False
+ amount = _amount(call.reported_usd)
+ return (
+ amount is not None
+ and counters["billable_requests"] + counters["uncertain_requests"] <= counters["requests"]
+ and counters["reported_requests"] <= counters["billable_requests"]
+ and amount <= counters["reported_requests"] * _SERVICE_REPORTED_USD_CEILING
+ )
+
+
+def _queue_key(call: UsageCall | ServiceUsageCall) -> tuple:
+ """Keep invalid service calls separate until the ledger repairs each one."""
+
+ key = call.fold_key
+ if isinstance(call, ServiceUsageCall) and not _service_call_is_foldable(call):
+ return (*key, id(call))
+ return key
+
+
@dataclass
class _QueuedRow:
"""One queued row and the future every call folded into it is waiting on."""
- call: UsageCall
+ call: UsageCall | ServiceUsageCall
done: "asyncio.Future[None]"
@@ -2084,7 +2587,7 @@ class UsageWriter:
):
self.ledger = ledger
self._durability_wait = durability_wait
- self._pending: dict[tuple[str, str, str, str, int, bool], _QueuedRow] = {}
+ self._pending: dict[tuple, _QueuedRow] = {}
# Where context tiers come from: the valuation's table factory, and the
# table last read from it with the monotonic instant it was read.
self._price_table = price_table
@@ -2137,17 +2640,54 @@ class UsageWriter:
without tiers (no models.dev copy yet), records the base tier.
"""
- call = UsageCall(
- source_id=source_id,
- model_id=model_id,
- usage=usage,
- at=at,
- context_tier=self._context_tier(model_id, usage),
+ return self._queue(
+ UsageCall(
+ source_id=source_id,
+ model_id=model_id,
+ usage=usage,
+ at=at,
+ context_tier=self._context_tier(model_id, usage),
+ )
)
+
+ def record_service(
+ self,
+ *,
+ source_id: str,
+ service_id: str,
+ billable: bool,
+ uncertain: bool = False,
+ reported_usd: Optional[float] = None,
+ at: datetime,
+ ) -> "asyncio.Future[None]":
+ """Own one sent search-service request and queue it, as `record` does a model call.
+
+ Synchronous for the same reason, so a stopped turn still meters a request
+ it sent (`web-search-services.md` §4.3). `billable` is the catalog's billing
+ rule's answer; `uncertain` is a request whose billing is unknown, which is
+ never also billable. `reported_usd` is the vendor's own figure for a billable
+ request, already bounded by the caller; the ledger's relations are the
+ backstop, and a figure that breaks them is recorded as a floor, not as sent.
+ """
+
+ return self._queue(
+ ServiceUsageCall(
+ source_id=source_id,
+ service_id=service_id,
+ at=at,
+ billable_requests=_flag_count(billable),
+ uncertain_requests=_flag_count(uncertain),
+ reported_requests=int(reported_usd is not None),
+ reported_usd=reported_usd if reported_usd is not None else 0.0,
+ )
+ )
+
+ def _queue(self, call: UsageCall | ServiceUsageCall) -> "asyncio.Future[None]":
done = asyncio.get_running_loop().create_future
- if (queued := self._pending.get(call.fold_key)) is None:
+ key = _queue_key(call)
+ if (queued := self._pending.get(key)) is None:
queued = _QueuedRow(call=call, done=done())
- self._pending[call.fold_key] = queued
+ self._pending[key] = queued
else:
queued.call = queued.call.folded_with(call)
if self._flush is None or self._flush.done():
diff --git a/core/hosted_activity.py b/core/hosted_activity.py
index 6f990f622..e0965a44b 100644
--- a/core/hosted_activity.py
+++ b/core/hosted_activity.py
@@ -12,23 +12,31 @@ later surface render the same facts for a native and a proxied call alike:
Nothing here prices, routes or replays anything: it reads what the producers
recorded. ``HostedActivity.to_payload`` is the wire shape a ``toolcall`` row
carries as ``content.hosted`` (version 1), read by the Web activity group.
+
+A search chain that reached a search-capable candidate records ``attempts``
+(``web-search-services.md`` §4.3). This module alone decides, from those facts
+and each Source's current state, who ran the call, what it cost, the switch
+note, and each entry's reason and repair; the IM line and the Web card only put
+the decided keys into words.
"""
from __future__ import annotations
-from dataclasses import dataclass
-from typing import Any, Callable, Literal, Optional
+from dataclasses import dataclass, fields
+from typing import Any, Callable, Literal, Mapping, Optional
from core.agent_core.messages import (
HOSTED_ERROR_CODES,
AssistantMessage,
HostedAction,
+ HostedAttempt,
HostedCost,
HostedImage,
HostedResult,
HostedSource,
HostedToolBlock,
ProxyExecution,
+ ServiceExecutorOrigin,
ToolCallBlock,
)
from core.citations import safe_url
@@ -41,12 +49,76 @@ HOSTED_ACTIVITY_VERSION = 1
LINE_SUBJECT_MAX_CHARS = 60
SourceNames = Callable[[str], Optional[str]]
+#: A Source as Model Hub holds it now: ``protocol``, ``vendor``, ``needs_action`` (its ``needs_action`` or ``error``
+#: detail key, absent while it is healthy) and, for a search-capable Source, its effective ``enabled``. ``None`` is a
+#: Source removed since. A caller that could not read Model Hub passes no ``SourceState`` at all.
+SourceState = Callable[[str], Optional[Mapping[str, Any]]]
+
+_NEEDS_ACTION = "models.source.needs_action."
+# The Source health each search-service failure sets (§4.2), so a failed entry is matched against the Source's
+# current health even when the producer recorded none beside the code.
+_CODE_HEALTH = {
+ "service_key_invalid": f"{_NEEDS_ACTION}credential_revoked",
+ "service_balance": f"{_NEEDS_ACTION}balance_exhausted",
+ "service_limit": f"{_NEEDS_ACTION}spend_limit_reached",
+}
+_HEALTH_CODE = {health: code for code, health in _CODE_HEALTH.items()}
+# Failures with a reason of their own; any other, a model executor's included, says it failed.
+_FAILURE_REASONS = (
+ "service_key_invalid",
+ "service_balance",
+ "service_limit",
+ "service_unavailable",
+ "service_refused",
+ "service_unreadable",
+)
+# Each existing Source health detail's repair; any other detail (the generic error) points to the Source.
+_REPAIRS = {
+ f"{_NEEDS_ACTION}credential_revoked": "repair.key",
+ f"{_NEEDS_ACTION}oauth_expired": "repair.reauthorize",
+ f"{_NEEDS_ACTION}balance_exhausted": "repair.balance",
+ f"{_NEEDS_ACTION}spend_limit_reached": "repair.limit",
+ f"{_NEEDS_ACTION}plan_excludes_product": "repair.plan",
+ f"{_NEEDS_ACTION}account_banned": "repair.account",
+}
+# A tool-only search Source leaves a balance or limit state only through "重新启用", so its repair ends with it; a
+# model Source recovers on its own paths (§4.2). Tavily's catalog row names both of its limits' repairs (432, 433).
+_SEARCH_REPAIRS = {
+ f"{_NEEDS_ACTION}balance_exhausted": "repair.balanceReenable",
+ f"{_NEEDS_ACTION}spend_limit_reached": "repair.limitReenable",
+}
+_VENDOR_SEARCH_REPAIRS = {("tavily", f"{_NEEDS_ACTION}spend_limit_reached"): "repair.tavilyLimit"}
def _no_names(_source_id: str) -> Optional[str]:
return None
+@dataclass(frozen=True)
+class HostedAttemptView(HostedAttempt):
+ """One recorded chain entry as the surfaces show it now.
+
+ The recorded facts are kept as written, except ``label``, which is the Source's current name (the recorded one
+ for a Source removed since), and ``superseded``, which is also set when the Source's current health no longer
+ matches the failure. ``reason_key`` says what happened to the Source in this call and ``remedy_key`` what it
+ needs now, if anything, both relative to each surface's hosted-tool copy (``hostedTools.`` for IM,
+ ``chat.agentActivity.hosted.`` for the Web). A completed entry has no reason.
+ """
+
+ reason_key: Optional[str] = None
+ remedy_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class HostedSwitch:
+ """A completed search that moved past Sources that failed or were blocked: their names, why (one Source's own
+ reason, or "failed" for several), and the Source that answered."""
+
+ sources: tuple[str, ...]
+ reason_key: str
+ to: str
+
+
@dataclass(frozen=True)
class HostedActivity:
"""One hosted call as the user sees it."""
@@ -91,6 +163,11 @@ class HostedActivity:
# with its current name.
fallback_source_id: Optional[str] = None
fallback_source_name: Optional[str] = None
+ # Every candidate a search chain reached (§4.3), as shown now; None for the released shape, which has none.
+ attempts: Optional[tuple[HostedAttemptView, ...]] = None
+ # Whether a search service or a model executor ran it; None when the record does not say (released records).
+ executor_kind: Optional[Literal["service", "model"]] = None
+ switch: Optional[HostedSwitch] = None
@property
def completed(self) -> bool:
@@ -129,10 +206,19 @@ class HostedActivity:
"revised_prompt": self.revised_prompt,
"duration_ms": self.duration_ms,
"response_id": self.response_id,
+ "executor_kind": self.executor_kind,
}
payload.update({key: value for key, value in optional.items() if value is not None})
if self.extra_queries:
payload["extra_queries"] = list(self.extra_queries)
+ if self.attempts is not None:
+ payload["attempts"] = [_attempt_payload(attempt) for attempt in self.attempts]
+ if self.switch is not None:
+ payload["switch"] = {
+ "sources": list(self.switch.sources),
+ "reason_key": self.switch.reason_key,
+ "to": self.switch.to,
+ }
if self.fallback_source_id is not None:
fallback: dict[str, Any] = {"source_id": self.fallback_source_id}
if self.fallback_source_name is not None:
@@ -142,12 +228,34 @@ class HostedActivity:
cost: dict[str, Any] = {"basis": self.cost.basis, "calls": self.cost_calls}
if self.cost.usd is not None:
cost["usd"] = self.cost.usd
+ if self.cost.estimate:
+ cost["estimate"] = True
if self.cost_at_least:
cost["at_least"] = True
payload["cost"] = cost
return payload
+def _attempt_payload(attempt: HostedAttemptView) -> dict[str, Any]:
+ out: dict[str, Any] = {
+ "source_id": attempt.source_id,
+ "label": attempt.label,
+ "kind": attempt.kind,
+ "outcome": attempt.outcome,
+ }
+ for name in ("error_code", "skipped", "retry_at", "needs_action", "superseded", "reason_key", "remedy_key"):
+ value = getattr(attempt, name)
+ if value is not None:
+ out[name] = value
+ if attempt.cost is not None:
+ out["cost"] = {"basis": attempt.cost.basis}
+ if attempt.cost.usd is not None:
+ out["cost"]["usd"] = attempt.cost.usd
+ if attempt.cost.estimate:
+ out["cost"]["estimate"] = True
+ return out
+
+
def _source_payload(source: HostedSource) -> dict[str, Any]:
"""A source as the card links it: only a URL a browser should open, held to the rule citation links are
(``safe_url``). Any other string a provider gave stays readable as the source's title, never a link."""
@@ -244,15 +352,117 @@ def native_activities(
return activities
+def _repair(detail: str, current: Mapping[str, Any]) -> str:
+ """What a Source in health ``detail`` needs: the detail's existing repair, ending with "重新启用" for a tool-only
+ search Source in a balance or limit state."""
+
+ if current.get("protocol") == "search":
+ repair = _VENDOR_SEARCH_REPAIRS.get((current.get("vendor"), detail)) or _SEARCH_REPAIRS.get(detail)
+ if repair:
+ return repair
+ return _REPAIRS.get(detail, "repair.error")
+
+
+def _view(attempt: HostedAttempt, source_names: SourceNames, source_state: Optional[SourceState]) -> HostedAttemptView:
+ """One entry as shown now. Current state governs every repair, never the record: a Source repaired, re-enabled
+ or removed since shows none, and without a Model Hub read nothing is offered at all. Only a failed entry can be
+ superseded: explicitly, by a removal, or by a current health other than the one its failure set (§4.3)."""
+
+ current = source_state(attempt.source_id) if source_state is not None else None
+ superseded = bool(attempt.superseded)
+ reason: Optional[str] = None
+ remedy: Optional[str] = None
+ if attempt.outcome == "failed":
+ health = attempt.needs_action or _CODE_HEALTH.get(attempt.error_code or "")
+ if source_state is not None and not superseded:
+ superseded = current is None or (health is not None and current.get("needs_action") != health)
+ if superseded:
+ reason = "reason.superseded"
+ else:
+ reason = f"reason.{attempt.error_code}" if attempt.error_code in _FAILURE_REASONS else "reason.failed"
+ if health is not None and current is not None:
+ remedy = _repair(health, current)
+ elif attempt.skipped == "blocked":
+ # The skip stays as recorded; its repair is whatever the Source needs now, if anything.
+ recorded = _HEALTH_CODE.get(attempt.needs_action or "")
+ reason = f"reason.{recorded}" if recorded else "skip.blocked"
+ if current is not None and current.get("needs_action"):
+ remedy = _repair(current["needs_action"], current)
+ elif attempt.skipped is not None:
+ reason = f"skip.{attempt.skipped}"
+ if attempt.skipped == "disabled" and current is not None and current.get("enabled") is False:
+ remedy = "repair.disabled"
+ return HostedAttemptView(
+ **{field.name: getattr(attempt, field.name) for field in fields(HostedAttempt)}
+ | {"label": source_names(attempt.source_id) or attempt.label, "superseded": superseded or None},
+ reason_key=reason,
+ remedy_key=remedy,
+ )
+
+
+def _last_tried(attempts: tuple[HostedAttemptView, ...]) -> Optional[int]:
+ """Where the entry that ran the call is: the last one tried."""
+
+ return next((index for index in range(len(attempts) - 1, -1, -1) if attempts[index].outcome != "skipped"), None)
+
+
+def _switch(status: str, attempts: tuple[HostedAttemptView, ...], last: Optional[int]) -> Optional[HostedSwitch]:
+ """The Sources a completed chain moved past before its answer: the failed ones and the blocked or disabled
+ skips. A Source cooling down, refusing a long query or gone since the turn began was not a failure of its own."""
+
+ if status != "completed" or last is None or attempts[last].outcome != "completed":
+ return None
+ winner = attempts[last]
+ before = [
+ attempt
+ for attempt in attempts[:last]
+ if attempt.outcome == "failed" or attempt.skipped in ("blocked", "disabled")
+ ]
+ if not before:
+ return None
+ reason = before[0].reason_key if len(before) == 1 and before[0].reason_key else "reason.failed"
+ return HostedSwitch(sources=tuple(attempt.label for attempt in before), reason_key=reason, to=winner.label)
+
+
+def _attempts_cost(attempts: tuple[HostedAttemptView, ...]) -> tuple[Optional[HostedCost], bool]:
+ """What a chain cost, from its tried entries alone (§4.3), and whether that is only a lower bound.
+
+ A skip sent nothing. An exact $0 is never an estimate, so the total's basis comes from its non-zero figures: it
+ is approximate when any of them is a list price or an estimate, and an all-zero total is an exact "$0". A tried
+ entry without a cost makes a known total a lower bound; with no known figure the cost is unknown.
+ """
+
+ tried = [attempt for attempt in attempts if attempt.outcome != "skipped"]
+ known = [attempt.cost for attempt in tried if attempt.cost is not None]
+ if not known:
+ return None, False
+ unpriced = len(known) < len(tried)
+ priced = [cost for cost in known if cost.basis != "included"]
+ if not priced:
+ return (HostedCost(basis="included"), False) if not unpriced else (None, False)
+ nonzero = [cost for cost in priced if cost.usd]
+ reported = bool(nonzero) and all(cost.basis == "reported" for cost in nonzero)
+ estimate = reported and any(cost.estimate for cost in nonzero)
+ usd = round(sum(cost.usd or 0.0 for cost in priced), 6)
+ return HostedCost(basis="reported" if reported else "list", usd=usd, estimate=True if estimate else None), unpriced
+
+
def proxy_activity(
call: ToolCallBlock,
result: HostedResult,
*,
source_names: SourceNames = _no_names,
+ source_state: Optional[SourceState] = None,
duration_ms: Optional[int] = None,
) -> HostedActivity:
"""A hosted call that ran outside the model: the model's own call, and the record its search executor
- (``proxy``) or image endpoint (``direct``) returned."""
+ (``proxy``) or image endpoint (``direct``) returned.
+
+ With ``attempts`` (§4.3) the chain alone says who ran it and what it cost: the last tried entry, and the sum of
+ the tried entries. ``execution`` then adds only the model of that same entry, which the entry does not store;
+ a chain that tried nothing names no executor, whatever ``execution`` says. Without them, the released reading
+ holds, and a ``search_api`` origin still marks a search service.
+ """
arguments = call.arguments if isinstance(call.arguments, dict) else {}
subject = next(
@@ -261,10 +471,37 @@ def proxy_activity(
)
size = arguments.get("size") if isinstance(arguments.get("size"), str) else None
execution = result.execution
- cost, at_least = _chain_cost(execution)
+ attempts = None
+ last = switch = None
+ executor = execution
+ if result.record.attempts is None:
+ cost, at_least = _chain_cost(execution)
+ else:
+ attempts = tuple(_view(attempt, source_names, source_state) for attempt in result.record.attempts)
+ index = _last_tried(attempts)
+ last = attempts[index] if index is not None else None
+ if last is None or execution is None or execution.executor_source_id != last.source_id:
+ executor = None
+ cost, at_least = _attempts_cost(attempts)
+ switch = _switch(result.record.status, attempts, index)
+ origin = executor.executor_origin if executor is not None else None
+ service = isinstance(origin, ServiceExecutorOrigin)
+ kind = last.kind if last is not None else ("service" if service else None)
# What the executor reports it did (an image's rendered prompt and resolved size and quality), read as a native
# call's block action is.
ran = result.action if result.action is not None and result.action.type == "generate" else None
+ if origin is not None and not service and kind != "service":
+ model = origin.model
+ else:
+ # The model a refused image call named: it never moves to another (§7.4). A search service has no model:
+ # its catalog service id is not shown (§4.3).
+ model = ran.model if ran is not None and attempts is None and origin is None else None
+ if last is not None:
+ source_id, source_name = last.source_id, last.label
+ elif executor is not None:
+ source_id, source_name = executor.executor_source_id, source_names(executor.executor_source_id)
+ else:
+ source_id = source_name = None
return HostedActivity(
call_id=call.id,
tool=call.name,
@@ -276,15 +513,10 @@ def proxy_activity(
subject=subject,
action=None,
extra_queries=(),
- provider=execution.executor_origin.provider if execution is not None else None,
- source_id=execution.executor_source_id if execution is not None else None,
- source_name=source_names(execution.executor_source_id) if execution is not None else None,
- model=(
- execution.executor_origin.model
- if execution is not None
- # The model a refused image call named: it never moves to another (§7.4).
- else ran.model if ran is not None else None
- ),
+ provider=origin.provider if origin is not None else None,
+ source_id=source_id,
+ source_name=source_name,
+ model=model,
sources=tuple(result.record.sources),
images=tuple(result.record.images or ()),
size=(ran.size if ran is not None and ran.size else size),
@@ -298,6 +530,9 @@ def proxy_activity(
source_names(result.fallback_from.source_id) if result.fallback_from is not None else None
),
cost_at_least=at_least,
+ attempts=attempts,
+ executor_kind=kind,
+ switch=switch,
)
@@ -326,18 +561,19 @@ def _runner_label(activity: HostedActivity, escape: Callable[[str], str]) -> Opt
"""Who ran a call, as the IM line names it: its vendor's catalog label, else the Source's own name.
A Source added as a compatible endpoint has the vendor id ``custom``, which names no vendor, so its name is the
- only thing that tells the reader where the call ran. A Source name is the user's text, so it is made inert. A
- vendor id with neither stays as it is, as for a row stored without a Source.
+ only thing that tells the reader where the call ran. A search service is named by its Source first, as the user
+ named it (§4.3). A Source name is the user's text, so it is made inert. A vendor id with neither stays as it is,
+ as for a row stored without a Source.
"""
- if not activity.provider:
- return None
from vibe.model_hub_runtime.api_key_vendors import catalog_api_key_vendor_label
- label = catalog_api_key_vendor_label(activity.provider)
- if label:
+ label = catalog_api_key_vendor_label(activity.provider) if activity.provider else None
+ if label and activity.executor_kind != "service":
return label
- return _untrusted(activity.source_name, escape) if activity.source_name else activity.provider
+ if activity.source_name:
+ return _untrusted(activity.source_name, escape)
+ return label or activity.provider
def _usd(value: float) -> str:
@@ -364,7 +600,8 @@ def _ran(activity: HostedActivity, lang: str, escape: Callable[[str], str]) -> l
"""How a completed call ran and what it produced, as the IM line names them.
A direct image call names the image model and the image's size rather than a vendor: the model is what the call
- picked, and the image is the result. A proxied search names its executor's model beside the vendor.
+ picked, and the image is the result. A proxied search names its executor's model beside the vendor, and a search
+ that moved past failing Sources says so in place of how it ran.
"""
if activity.mode == "direct":
@@ -373,12 +610,18 @@ def _ran(activity: HostedActivity, lang: str, escape: Callable[[str], str]) -> l
more = _count(activity, lang) if len(activity.images) > 1 else None
return [_untrusted(activity.model, escape) if activity.model else None, size, more]
vendor = _runner_label(activity, escape)
- if not vendor:
- mode = None
- elif activity.mode == "proxy" and activity.fallback_source_id is not None:
+ if vendor and activity.mode == "proxy" and activity.fallback_source_id is not None:
# Why it ran by proxy: the turn's own Source refused the native tool (§8.3, mockup 06).
refused_by = _untrusted(activity.fallback_source_name or activity.fallback_source_id, escape)
mode = i18n_t("hostedTools.mode.fallback", lang, source=refused_by, provider=vendor)
+ elif activity.switch is not None:
+ # Why it ran where it did: the Sources before it failed or were blocked (§6.5).
+ mode = _switch_text(activity.switch, lang, escape)
+ elif not vendor:
+ mode = None
+ elif activity.executor_kind == "service":
+ # A search service is named alone: "🔎 网页搜索 “…” · Tavily · 5 个来源" (§6.5).
+ mode = vendor
elif activity.mode == "proxy" and activity.model:
mode = i18n_t("hostedTools.mode.proxyModel", lang, provider=vendor, model=_untrusted(activity.model, escape))
else:
@@ -408,8 +651,9 @@ def _cost(activity: HostedActivity, lang: str) -> Optional[str]:
elif cost.usd is None:
return None
else:
- key = "hostedTools.cost.list" if cost.basis == "list" else "hostedTools.cost.reported"
- text = i18n_t(key, lang, usd=_usd(cost.usd))
+ # A zero is exact; any other figure is approximate when it is a list price or the vendor's own estimate.
+ approximate = cost.usd != 0 and (cost.basis == "list" or bool(cost.estimate))
+ text = i18n_t(f"hostedTools.cost.{'list' if approximate else 'reported'}", lang, usd=_usd(cost.usd))
if activity.cost_at_least:
text = i18n_t("hostedTools.cost.atLeast", lang, cost=text)
if activity.cost_calls > 1:
@@ -429,12 +673,33 @@ def _error_text(activity: HostedActivity, lang: str) -> str:
return activity.error or ""
+def _switch_text(switch: HostedSwitch, lang: str, escape: Callable[[str], str]) -> str:
+ names = i18n_t("hostedTools.listSeparator", lang).join(_untrusted(name, escape) for name in switch.sources)
+ failed = f"{names} {i18n_t(f'hostedTools.{switch.reason_key}', lang)}"
+ return i18n_t("hostedTools.switch", lang, failed=failed, provider=_untrusted(switch.to, escape))
+
+
+def _attempt_items(activity: HostedActivity, lang: str, escape: Callable[[str], str]) -> Optional[str]:
+ """Every Source a call that did not complete reached, whichever supplied its reason: each with what it needs
+ now, else what happened to it (§4.3)."""
+
+ if activity.completed or not activity.attempts:
+ return None
+ items = [
+ f"{_untrusted(attempt.label, escape)} {i18n_t(f'hostedTools.{key}', lang)}"
+ for attempt in activity.attempts
+ if (key := attempt.remedy_key or attempt.reason_key)
+ ]
+ return i18n_t("hostedTools.itemSeparator", lang).join(items) or None
+
+
def hosted_line(activity: HostedActivity, lang: str, *, escape: Callable[[str], str] = lambda text: text) -> str:
"""The one-line form IM shows per hosted call.
``🔎 Web search "query" · native (xAI) · 6 sources · $0.01``, or for an image
``🖼 Image generation "prompt" · gpt-image-2 · 1536×1024 · $0.02``. A call that did
- not complete says why instead of how it ran or what it found, and keeps a
+ not complete says why instead of how it ran or what it found, names every
+ Source its search chain reached with what each needs now, and keeps a
known cost (``HostedActivity.completed``). ``escape`` is the destination
formatter's literal-text operation (``escape_special_chars``), so a quoted
query such as ``*domain*`` reads as written rather than as markup.
@@ -450,5 +715,6 @@ def hosted_line(activity: HostedActivity, lang: str, *, escape: Callable[[str],
parts.append(
i18n_t(f"hostedTools.status.{activity.status}", lang, error=_untrusted(_error_text(activity, lang), escape))
)
+ parts.append(_attempt_items(activity, lang, escape))
parts.append(_cost(activity, lang))
return " · ".join(part for part in parts if part)
diff --git a/docs/plans/agent-core-contracts/message.schema.json b/docs/plans/agent-core-contracts/message.schema.json
index aff14e4ca..d8950c5bf 100644
--- a/docs/plans/agent-core-contracts/message.schema.json
+++ b/docs/plans/agent-core-contracts/message.schema.json
@@ -49,6 +49,31 @@
}
}
},
+ "ServiceExecutorOrigin": {
+ "type": "object",
+ "required": [
+ "provider",
+ "api",
+ "model"
+ ],
+ "additionalProperties": false,
+ "description": "A search service executor, not a model-wire origin.",
+ "properties": {
+ "provider": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Search vendor identity, for example `tavily` or `deepseek`."
+ },
+ "api": {
+ "const": "search_api"
+ },
+ "model": {
+ "type": "string",
+ "minLength": 1,
+ "description": "The catalog service id."
+ }
+ }
+ },
"LargeRef": {
"type": "object",
"required": [
@@ -924,6 +949,105 @@
}
}
},
+ "HostedAttempt": {
+ "type": "object",
+ "required": [
+ "source_id",
+ "label",
+ "kind",
+ "outcome"
+ ],
+ "additionalProperties": false,
+ "description": "One candidate reached by a search chain, including candidates skipped before a request.",
+ "properties": {
+ "source_id": {
+ "type": "string",
+ "pattern": "^src_[a-z0-9]{8,}$"
+ },
+ "label": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64
+ },
+ "kind": {
+ "enum": [
+ "service",
+ "model"
+ ]
+ },
+ "outcome": {
+ "enum": [
+ "completed",
+ "failed",
+ "skipped"
+ ]
+ },
+ "error_code": {
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]{0,63}$"
+ },
+ "skipped": {
+ "enum": [
+ "blocked",
+ "disabled",
+ "cooling",
+ "query_too_long",
+ "unavailable"
+ ]
+ },
+ "retry_at": {
+ "type": "string",
+ "minLength": 1
+ },
+ "needs_action": {
+ "type": "string",
+ "minLength": 1
+ },
+ "cost": {
+ "$ref": "#/definitions/HostedCost"
+ },
+ "superseded": {
+ "type": "boolean"
+ }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": {
+ "outcome": {
+ "const": "skipped"
+ }
+ }
+ },
+ "then": {
+ "required": [
+ "skipped"
+ ]
+ },
+ "else": {"not": {"required": ["skipped"]}}
+ },
+ {
+ "if": {"required": ["retry_at"]},
+ "then": {"required": ["skipped"], "properties": {"skipped": {"const": "cooling"}}}
+ },
+ {
+ "if": {
+ "properties": {
+ "outcome": {
+ "const": "completed"
+ }
+ }
+ },
+ "then": {
+ "not": {
+ "required": [
+ "error_code"
+ ]
+ }
+ }
+ }
+ ]
+ },
"HostedImage": {
"type": "object",
"required": [
@@ -999,6 +1123,12 @@
"items": {
"$ref": "#/definitions/HostedImage"
}
+ },
+ "attempts": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/HostedAttempt"
+ }
}
},
"dependencies": {
@@ -1154,7 +1284,8 @@
"basis"
],
"additionalProperties": false,
- "description": "`reported`: the provider's figure; `list`: computed by Model Hub's pricing module; `included`: a subscription Source, no per-call charge.",
+ "description": "`reported`: the provider's figure; `list`: computed by Model Hub's pricing module; `included`: a subscription Source, no per-call charge. `estimate` marks a vendor estimate; it does not change the reported basis.",
+ "allOf": [{"if": {"required": ["estimate"], "properties": {"estimate": {"const": true}}}, "then": {"required": ["usd"]}}],
"properties": {
"basis": {
"enum": [
@@ -1166,6 +1297,9 @@
"usd": {
"type": "number",
"minimum": 0
+ },
+ "estimate": {
+ "type": "boolean"
}
},
"if": {
@@ -1239,7 +1373,14 @@
]
},
"executor_origin": {
- "$ref": "#/definitions/Origin"
+ "oneOf": [
+ {
+ "$ref": "#/definitions/Origin"
+ },
+ {
+ "$ref": "#/definitions/ServiceExecutorOrigin"
+ }
+ ]
},
"executor_source_id": {
"type": "string",
diff --git a/docs/plans/model-hub-contracts/README.md b/docs/plans/model-hub-contracts/README.md
index a14e8a1cd..b518ba8a2 100644
--- a/docs/plans/model-hub-contracts/README.md
+++ b/docs/plans/model-hub-contracts/README.md
@@ -1,8 +1,35 @@
# Model Hub contracts
-Status: **contract_version 18**, 2026-10-20: web-search settings and dormant Tools
-read (S1b, `../web-search-services.md` §3.2/§3.5). The RC tag `gh-v3.2.2rc12`
-contains S1a and v17, so these additions open a new event rather than changing v17.
+Status: **contract_version 19**, 2026-10-21: dormant web-search-service readers
+(S2a, `../web-search-services.md` §4.3, §6.5, §8). The RC tag `gh-v3.2.2rc13`
+carries v18, so these additions open a new event rather than changing v18.
+- C-1 (`../agent-core-contracts/message.schema.json`) accepts `HostedRecord.attempts[]`
+ (`HostedAttempt`), `HostedCost.estimate`, and a `ServiceExecutorOrigin`
+ (`{provider, api: "search_api", model}`) beside the released `Origin` in
+ `ProxyExecution.executor_origin`. `HOSTED_ERROR_CODES` gains the six `service_*`
+ attempt codes, `search_query_too_long` and `search_sources_blocked`. `HostedSource`
+ and the assistant's four-protocol `Origin` are unchanged, and released records load
+ and serialize unchanged.
+- Capability evidence (`capability-evidence.schema.json`) and the Tools read's
+ `status.latest_ok.mode` and `status.verified[].mode`
+ (`hosted-tools-status.schema.json`) accept `mode: "service"`.
+- Usage (`usage-summary.schema.json`, `api.md` Search-service usage): service ledger
+ rows keyed by Source and catalog `service_id`, the required `services[]`,
+ `kind: "service"` bucket rows, `service_reported_usd` and `excluded_service_requests`
+ on totals and days, and `pricing.service_price_date`. Model counts never include
+ service requests.
+- These are readers only. No search runs, no service request is metered, no service
+ evidence is written, and `SEARCH_SERVICES_ACTIVE` stays off; service candidates and
+ `service_vendors` remain absent from the Tools read. S2b owns the producers and
+ activation, and the downgrade boundary of `../web-search-services.md` §12 begins
+ when it writes these shapes.
+- The versioned mirrors advance together; persisted TurnProvenance retains v5–v18
+ and adds v19.
+
+It builds on v18 (2026-10-20, carried by `gh-v3.2.2rc13`): web-search settings and
+dormant Tools read (S1b, `../web-search-services.md` §3.2/§3.5). The RC tag
+`gh-v3.2.2rc12` contains S1a and v17, so these additions opened a new event rather
+than changing v17.
- V2 adds `prefer_native`, partial Source-keyed `services` overrides (`results` and
`enabled`) with catalog result-count clamping, and server-owned `executor_order_kinds`
saved with each web-search order.
@@ -20,8 +47,8 @@ contains S1a and v17, so these additions open a new event rather than changing v
S1b's unshipped `content` setting and vendor content flags are removed from this
v18 event. A dev build's saved `services.<id>.content` is ignored with the normal
unknown-field warning, preserving the tool switch, search opt-outs and orders.
-- The versioned mirrors advance together; persisted TurnProvenance retains v5–v17
- and adds v18. The rc12 hosted-tools loader ignores new optional config fields
+- The versioned mirrors advanced together; persisted TurnProvenance retained v5–v17
+ and added v18. The rc12 hosted-tools loader ignores new optional config fields
and retains the whole-tool switch and both orders, not per-Source service
opt-outs. An rc12 config write drops those overrides; re-upgrading then uses
service defaults, so DeepSeek's opt-out must be reapplied before execution.
@@ -296,7 +323,7 @@ comparison. A gate may not report success by comparing stale input with itself.
## Version closure
-`contract_version` 18 must coexist in all registered version locations on the same tested head:
+`contract_version` 19 must coexist in all registered version locations on the same tested head:
- `mirror-registry.json`
- `agent-chain.schema.json`
diff --git a/docs/plans/model-hub-contracts/adapter-interface.py b/docs/plans/model-hub-contracts/adapter-interface.py
index d1002c869..7c21d1da1 100644
--- a/docs/plans/model-hub-contracts/adapter-interface.py
+++ b/docs/plans/model-hub-contracts/adapter-interface.py
@@ -1,4 +1,4 @@
-"""Model Hub EngineAdapter interface. FINAL CONTRACT v18 (2026-10-20).
+"""Model Hub EngineAdapter interface. FINAL CONTRACT v19 (2026-10-21).
This file is the canonical adapter boundary and must remain byte-identical to
``core/handlers/model_hub/adapter.py``. The adapter owns one-Source operations:
diff --git a/docs/plans/model-hub-contracts/agent-chain.schema.json b/docs/plans/model-hub-contracts/agent-chain.schema.json
index 66e515f6c..755c7154d 100644
--- a/docs/plans/model-hub-contracts/agent-chain.schema.json
+++ b/docs/plans/model-hub-contracts/agent-chain.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "backend", "model_id", "manual_override", "route_origin", "chain", "current", "supply_state"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 18 },
+ "contract_version": { "const": 19 },
"backend": { "enum": ["claude", "codex", "opencode", "vibey"] },
"model_id": { "type": "string" },
"manual_override": {
@@ -255,7 +255,7 @@
],
"examples": [
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"model_id": "unlisted-model",
"manual_override": null,
@@ -265,7 +265,7 @@
"supply_state": "ok"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -275,7 +275,7 @@
"supply_state": "ok"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "claude",
"model_id": "claude-opus-4-6",
"manual_override": null,
@@ -285,7 +285,7 @@
"supply_state": "waiting"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "opencode",
"model_id": "glm-5.2",
"manual_override": { "hops": [{ "source_id": "src_relay9c1x", "model_id": "glm-5.2" }] },
@@ -295,7 +295,7 @@
"supply_state": "waiting"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -305,7 +305,7 @@
"supply_state": "interrupted"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -315,7 +315,7 @@
"supply_state": "interrupted"
},
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "claude",
"model_id": "claude-haiku-4-5",
"manual_override": null,
diff --git a/docs/plans/model-hub-contracts/api-response.schema.json b/docs/plans/model-hub-contracts/api-response.schema.json
index 1cd68951e..2786cad03 100644
--- a/docs/plans/model-hub-contracts/api-response.schema.json
+++ b/docs/plans/model-hub-contracts/api-response.schema.json
@@ -61,7 +61,7 @@
"required": ["ok", "contract_version", "probe"],
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"probe": {"$ref": "model-hub/source-probe-result.schema.json"}
}
},
@@ -160,7 +160,7 @@
"SuccessCore": {
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18}
+ "contract_version": {"const": 19}
}
},
"SourceListResponse": {
@@ -169,7 +169,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"sources": {"type": "array", "items": {"$ref": "#/definitions/SourceApi"}}
}
},
@@ -179,7 +179,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"observation": {"$ref": "model-hub/observation-result.schema.json"}
}
},
@@ -189,7 +189,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"source": {"$ref": "#/definitions/SourceApi"},
"added_to": {"type": "array", "items": {"$ref": "#/definitions/AddedTo"}},
"adopted_by": {"type": "array", "items": {"$ref": "#/definitions/AdoptedBy"}, "uniqueItems": true}
@@ -201,7 +201,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"source": {"$ref": "#/definitions/SourceApi"}
}
},
@@ -211,7 +211,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"source": {"$ref": "#/definitions/SourceApi"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
@@ -223,7 +223,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"source": {
"allOf": [
{"$ref": "#/definitions/SourceApi"},
@@ -241,7 +241,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
}
@@ -252,7 +252,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"agents": {"type": "array", "items": {"$ref": "#/definitions/AgentSupplyApi"}}
}
},
@@ -262,7 +262,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"agent": {"$ref": "#/definitions/AgentSupplyApi"}
}
},
@@ -279,7 +279,7 @@
],
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"agent": {"$ref": "#/definitions/AgentSupplyApi"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}, "uniqueItems": true},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}, "uniqueItems": true}
@@ -304,7 +304,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": false},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"error": {"const": "candidate_suppliers_changed"},
"detail": {"type": "string", "minLength": 1},
"changed": {
@@ -324,7 +324,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"agent": {
"type": "object",
"required": ["backend", "mode", "catalog_models"],
@@ -425,7 +425,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"candidates": {
"type": "object",
"required": ["builtin", "providers", "in_list"],
@@ -444,7 +444,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"matches": {
"type": "array",
"maxItems": 8,
@@ -478,7 +478,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"chain": {"$ref": "model-hub/agent-chain.schema.json"}
}
},
@@ -488,7 +488,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"chains": {"type": "array", "items": {"$ref": "model-hub/agent-chain.schema.json"}}
}
},
@@ -498,7 +498,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"chain": {"$ref": "model-hub/agent-chain.schema.json"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
@@ -510,7 +510,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"probe": {"$ref": "model-hub/probe-result.schema.json"}
}
},
@@ -520,7 +520,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"events": {"type": "array", "items": {"$ref": "model-hub/resolution-event.schema.json"}}
}
},
@@ -530,7 +530,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"usage": {"$ref": "model-hub/usage-summary.schema.json"}
}
},
@@ -540,7 +540,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"quota": {"$ref": "model-hub/quota-summary.schema.json"}
}
},
@@ -550,7 +550,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"hosted_tools": {"$ref": "model-hub/hosted-tools-status.schema.json"}
}
},
@@ -560,7 +560,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -582,7 +582,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -605,7 +605,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -630,7 +630,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18}
+ "contract_version": {"const": 19}
}
},
"RuntimeApi": {
@@ -652,7 +652,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"scan": {"$ref": "model-hub/migration-scan.schema.json"}
}
},
@@ -662,7 +662,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"applied": {"type": "integer", "minimum": 0},
"sources": {"type": "array", "items": {"$ref": "#/definitions/SourceApi"}},
"added_to": {"type": "array", "items": {"$ref": "#/definitions/AddedTo"}}
@@ -674,7 +674,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"provenance": {"$ref": "model-hub/turn-provenance.schema.json"}
}
},
@@ -685,7 +685,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"provenance": {
"anyOf": [
{"$ref": "model-hub/turn-provenance.schema.json"},
@@ -700,7 +700,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 18},
+ "contract_version": {"const": 19},
"runtime": {"$ref": "#/definitions/RuntimeApi"}
}
}
diff --git a/docs/plans/model-hub-contracts/api.md b/docs/plans/model-hub-contracts/api.md
index 44442b511..ebaf8f212 100644
--- a/docs/plans/model-hub-contracts/api.md
+++ b/docs/plans/model-hub-contracts/api.md
@@ -8,11 +8,11 @@ credential redaction and supply-impact confirmation rules still apply; unknown
API siblings retain the Owner default.
-Status: **Normative, `contract_version` 18** — Model Hub implementations must conform, and the response conformance guard enumerates this route table and validates one real server response for every route.
+Status: **Normative, `contract_version` 19** — Model Hub implementations must conform, and the response conformance guard enumerates this route table and validates one real server response for every route.
-Success envelope: `{ok: true, contract_version: 18, ...}`.
+Success envelope: `{ok: true, contract_version: 19, ...}`.
Failure envelope:
-`{ok: false, contract_version: 18, error: <machine_code>, detail?: <i18n_key>}`.
+`{ok: false, contract_version: 19, error: <machine_code>, detail?: <i18n_key>}`.
`detail` is always a string. Structured error data lives in a named sibling.
Guarded mutation refusals specialize that envelope through
`guard-refusal.schema.json`; both report arrays are required and together form the plan
@@ -24,7 +24,7 @@ table. The contract guard requires the two endpoint sets to be identical, requir
exercised HTTP response for every registry entry, and validates that response against
the route's named schema.
-The shared envelope and every versioned nested contract carry `contract_version` 18, the
+The shared envelope and every versioned nested contract carry `contract_version` 19, the
terminal value. Supported persisted config shapes and historical TurnProvenance
remain readable; ephemeral envelopes use only the terminal version.
@@ -69,7 +69,7 @@ runtime open. Once models are configured it participates in the runtime Stop gua
| POST `/api/models/agents/<backend>/probe` | `{model?}` → `{probe: ProbeResult}` | Hub only. Direct returns the same `direct_mode` error. |
| GET `/api/models/agents/<backend>/provenance?model=<id>` | → `{provenance: TurnProvenance \| null}` | On-demand read of the most recently persisted retained record for this exact backend and canonical catalog model, regardless of outcome. Validates backend/model; absent history is null. Uses only the existing bounded store and never starts or syncs the engine. No history field is added to AgentChain. |
| GET `/api/models/events?limit=<n>&before=<id>` | → `{events: ResolutionEvent[]}` | Bounded source-resolution feed. |
-| GET `/api/models/usage?days=<n>` | → `{usage: UsageSummary \| UsageReport}` | The released `days` selector remains supported and is clamped to the retained window; a Source with no metered call is absent rather than reported as zero. The exclusive modern `window=24h\|7d\|30d\|60d` selector returns the dense temporal report; sending both selectors or an invalid `window` returns `400 invalid_parameter`. |
+| GET `/api/models/usage?days=<n>` | → `{usage: UsageSummary \| UsageReport}` | The released `days` selector remains supported and is clamped to the retained window; a Source with no metered call is absent rather than reported as zero. Search-service requests are reported in `services[]`, never in `sources[]` (see Search-service usage). The exclusive modern `window=24h\|7d\|30d\|60d` selector returns the dense temporal report; sending both selectors or an invalid `window` returns `400 invalid_parameter`. |
| GET `/api/models/quota` | → `{quota: QuotaSummary}` | Rate-limit windows of every hub-held subscription Source, from the vendor's own usage report, plus each Source's API-price `value` (see Subscription quota). Served from the server cache; a Source older than five minutes is re-read before answering, bounded by a short deadline, and a Source still being read is listed in `pending`. Never starts the engine. |
| POST `/api/models/quota/refresh` | → `{quota: QuotaSummary}` | Forced re-read. Rate-limited per Source to one vendor call every 30 seconds and suppressed while a Source cools down after a vendor 429; a suppressed Source returns its cached snapshot. |
| GET `/api/models/hosted-tools` | → `{hosted_tools: HostedToolsStatus}` | Models → Tools (`hosted-tools-status.schema.json`): every catalog tool with its switch (absent setting = on), its passive status from real use (`latest_ok`, current `refused[]`, per-pair `verified[]`), for a search tool the saved and effective executor order with every eligible executor candidate and its unit rates, and for `image_generate` the saved and effective default and the available image models. Memory only; nothing is probed. |
@@ -83,7 +83,7 @@ runtime open. Once models are configured it participates in the runtime Stop gua
| POST `/api/models/migration/scan` | → `{scan: MigrationScan}` | Read-only. |
| POST `/api/models/migration/apply` | `{item_ids: string[], clean_api_keys?: boolean}` → `{applied, sources, added_to}` | Applies one grouped, server-owned custody transaction. It checks saved configuration and custody locally, copies API keys without upstream validation, upgrades an existing native subscription Source in place when present, and commits Source/Routes/backend mode atomically. API-key originals are kept unless cleanup was selected. Pre-exposure failure is reversible; post-exposure recovery is forward-only and keeps the backend blocked until terminalized. |
| GET `/api/models/turns/<turn_id>/provenance` | → `{provenance: TurnProvenance}` or documented absence error | Debug read for exactly attributed Hub turns. |
-| GET `/api/models/runtime/status` | → `{runtime: RuntimeDependency}` | Read-only managed engine status. The nested object carries `contract_version` 18 and persisted user intent in `enabled`; `not_started` is installed lazy-start idleness, not an alarm. |
+| GET `/api/models/runtime/status` | → `{runtime: RuntimeDependency}` | Read-only managed engine status. The nested object carries `contract_version` 19 and persisted user intent in `enabled`; `not_started` is installed lazy-start idleness, not an alarm. |
| POST `/api/models/runtime/install` | → `{runtime: RuntimeDependency}` | Idempotently starts server-owned installation. It returns and persists `installing`; reload reads the same state. Uses the existing mutation authentication and CSRF guards. |
| POST `/api/models/runtime/start` | → `{runtime: RuntimeDependency}` | Persists `enabled: true` and explicitly starts the managed engine. Service startup restores this intent; runtime availability has no separate enable-confirmation step. Uses the existing mutation authentication and CSRF guards; status reads never start it. |
| POST `/api/models/runtime/stop` | → `{runtime: RuntimeDependency}` | Explicitly stops the managed engine, persists `enabled: false`, and returns it to `not_started`. The mutation is rejected with `runtime_in_use` while any native backend is configured for Hub mode or Avibe has catalog models, so disabling the shared runtime cannot strand a configured route. An empty Avibe catalog does not keep the runtime open. |
@@ -186,8 +186,9 @@ current date; around a DST transition the 24-hour view can touch three dates.
Each bucket carries `history_complete` independently of `token_reports`. A legacy
daily-only ledger can therefore contribute to daily reports while leaving affected
hourly buckets incomplete; its daily count is never assigned to an hour using
-`last_metered_at`. Bucket rows are sparse `(source_id, model_id)` pairs, and the
-`totals`, `sources`, and `days` fields aggregate those same measured bucket rows.
+`last_metered_at`. Bucket rows are sparse `(source_id, model_id)` pairs, followed by
+sparse `(source_id, service_id)` rows with `kind: "service"`, and the `totals`,
+`sources`, `services`, and `days` fields aggregate those same measured bucket rows.
### Native API-key migration
@@ -714,7 +715,7 @@ The terminal result of both ordinary API-key creation and OAuth creation is:
```json
{
"ok": true,
- "contract_version": 18,
+ "contract_version": 19,
"source": {
"id": "src_anthkey01",
"kind": "api_key",
@@ -824,7 +825,7 @@ Every guarded Source/inventory mutation uses the §4.5 envelope matrix and the c
```json
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "source_last_supplier",
"would_remove_hops": [],
"would_interrupt": [
@@ -963,7 +964,7 @@ API-key success:
```json
{
"ok": true,
- "contract_version": 18,
+ "contract_version": 19,
"source": {
"id": "src_relay9c1x",
"kind": "api_key",
@@ -1058,7 +1059,7 @@ Status and submit return the same terminal shape:
```json
{
"ok": true,
- "contract_version": 18,
+ "contract_version": 19,
"flow": {
"flow_id": "oaf_claude01",
"client_nonce": "ofn_01j5w8z7p4n6q2rt",
@@ -1131,9 +1132,9 @@ a valid `interrupted` chain.
```json
{
"ok": true,
- "contract_version": 18,
+ "contract_version": 19,
"chain": {
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -1160,7 +1161,7 @@ In Direct mode both chain and probe refuse with:
```json
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "direct_mode",
"detail": "models.hub.direct_mode"
}
@@ -1174,9 +1175,9 @@ A successful probe nests its result:
```json
{
"ok": true,
- "contract_version": 18,
+ "contract_version": 19,
"probe": {
- "contract_version": 18,
+ "contract_version": 19,
"backend": "claude",
"channel": "hub",
"reachable": false,
@@ -1199,7 +1200,7 @@ not-ready carries the closed i18n key `models.probe.native_cli_unavailable`.
```json
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"channel": "native_cli",
"reachable": true,
@@ -1212,7 +1213,7 @@ not-ready carries the closed i18n key `models.probe.native_cli_unavailable`.
```json
{
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"channel": "native_cli",
"reachable": false,
@@ -1228,7 +1229,7 @@ No candidate is an API error with a typed model-scoped state:
```json
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "probe_no_candidate",
"detail": "models.probe.no_candidate.waiting",
"supply": {
@@ -1419,7 +1420,7 @@ The store retains at most 500 exactly attributed settled turns with its existing
writes. Ambiguous attribution remains excluded; this is not a log of every upstream
request. Null means no matching retained record, including eviction. A newer served,
canceled or other record without a terminal error supersedes older error display.
-Success uses exactly `{ok: true, contract_version: 18, provenance: TurnProvenance | null}`;
+Success uses exactly `{ok: true, contract_version: 19, provenance: TurnProvenance | null}`;
there is no `success` field or envelope exception.
Local `engine_down` records may also contain `local_error_detail`, an OS-generated
@@ -1513,7 +1514,7 @@ ambiguous absence are explicit and distinguishable from an unknown turn:
```json
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "provenance_unavailable",
"detail": "models.provenance.direct_mode"
}
@@ -1522,7 +1523,7 @@ ambiguous absence are explicit and distinguishable from an unknown turn:
```json
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "provenance_unavailable",
"detail": "models.provenance.attribution_ambiguous"
}
@@ -1744,6 +1745,45 @@ carry a metered turn (grouped by bucket start date for hourly reports, as descri
under usage report windows). `label` is joined from current Source config, so it is `null`
for a Source that has since been removed and follows a rename immediately.
+### Search-service usage
+
+A sent search-service request reaches no model, so it is metered in its own ledger row
+per Source and catalog `service_id` (`../web-search-services.md` §4.3), with the same
+daily and hourly retention, row capacity and ceilings as a model row. A request that
+failed before it was sent is not metered. The row counts `requests` (sent),
+`billable_requests` (those the catalog's billing rule charges), `uncertain_requests`
+(sent, billing unknown), and `reported_requests` with `reported_usd`, the vendor's own
+figures for billable requests. The service-row write API exists, but nothing calls it
+before search execution is activated (`../web-search-services.md` §9).
+
+The counts keep `billable_requests + uncertain_requests ≤ requests` and
+`reported_requests ≤ billable_requests`, and `reported_usd` is a finite, non-negative
+amount no larger than `reported_requests` × $1, zero without a reported request. They
+are repaired on write and on read: a row that breaks a relation keeps `requests`,
+reduces its counts to their bounds, drops the reported quantities a reduced count no
+longer covers or that break their own bound, and becomes a lower bound, as does every
+row with an uncertain request. A repaired row's hourly history is incomplete. A ledger
+row without the additive fields reads them as zero. A row is told apart by its
+`service_id`; one naming both a model and a service is dropped as unreadable.
+
+Model counts in `totals`, `sources[]`, `days[]` and model bucket rows never include
+service requests. `services[]` has one entry per (Source, `service_id`) with a sent
+request in the window, busiest first: the counts, `last_metered_at`, the Source's
+`label` (`null` once the Source is removed) and the catalog's `service_label` (`null`
+once the catalog no longer lists the service). A tool-only Source appears only there;
+a Source that also supplies models keeps its model usage in `sources[]`.
+
+When `pricing` is present, each `services[]` entry and service bucket row also carries
+`reported_usd`, `api_cost_usd` and `api_cost_lower_bound`, and each `services[]` entry
+carries `priced`. `api_cost_usd` values every billable request at the current catalog's
+per-request list price; reported figures never replace or add to it. `totals` and
+`days[]` add the services' list valuation to their `api_cost_usd` and carry the reported
+figures apart in `service_reported_usd`. Their `excluded_service_requests` counts the
+billable requests of services the current catalog no longer prices, which, like an
+unpriced model's tokens, make the figure a lower bound. `pricing.service_price_date` is
+the oldest catalog price verification date among the priced services, absent when none
+is priced. Without a price table the service fields carry counts only.
+
## Runtime installation and host support
Every runtime response carries `host_platform`, and every status carries `error_key`.
diff --git a/docs/plans/model-hub-contracts/capability-evidence.schema.json b/docs/plans/model-hub-contracts/capability-evidence.schema.json
index acf623984..0b65bd9bb 100644
--- a/docs/plans/model-hub-contracts/capability-evidence.schema.json
+++ b/docs/plans/model-hub-contracts/capability-evidence.schema.json
@@ -41,7 +41,7 @@
"wire": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The wire the record was observed under: a digest of the engine release, the Avibe release, and the model's rendered fields that the Source identity does not cover (its registered reasoning tiers). With source_identity (vendor, protocol, base URL, credential, credential generation) it covers every Source field the engine renderer reads (model-hub-capability-model.md §3.3). An unsupported record under another stamp reads as unknown." },
"source_identity": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Digest of the Source identity at write time; a changed identity drops the record." },
"detail": { "type": "string", "minLength": 1, "maxLength": 64, "description": "unsupported only: HTTP status and upstream machine code, never upstream text." },
- "mode": { "enum": ["native", "executor", "direct"], "description": "verified only: how the call ran." }
+ "mode": { "enum": ["native", "executor", "service", "direct"], "description": "verified only: how the call ran." }
},
"if": { "properties": { "status": { "const": "unsupported" } } },
"then": { "required": ["detail"], "not": { "required": ["mode"] } },
diff --git a/docs/plans/model-hub-contracts/guard-refusal.schema.json b/docs/plans/model-hub-contracts/guard-refusal.schema.json
index 67a910ff6..3029168ed 100644
--- a/docs/plans/model-hub-contracts/guard-refusal.schema.json
+++ b/docs/plans/model-hub-contracts/guard-refusal.schema.json
@@ -61,7 +61,7 @@
],
"properties": {
"ok": { "const": false },
- "contract_version": { "const": 18 },
+ "contract_version": { "const": 19 },
"error": {
"enum": [
"source_last_supplier",
@@ -116,7 +116,7 @@
"examples": [
{
"ok": false,
- "contract_version": 18,
+ "contract_version": 19,
"error": "source_model_in_route_chain",
"detail": "modelHub.errors.source_model_in_route_chain",
"would_remove_hops": [
diff --git a/docs/plans/model-hub-contracts/hosted-tools-status.schema.json b/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
index 9ef589313..383217a5a 100644
--- a/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
+++ b/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
@@ -37,7 +37,7 @@
"properties": {
"source_id": { "$ref": "#/definitions/SourceId" },
"model_id": { "type": "string", "minLength": 1 },
- "mode": { "enum": ["native", "executor", "direct"] },
+ "mode": { "enum": ["native", "executor", "service", "direct"] },
"at": { "$ref": "#/definitions/Moment" }
}
}
@@ -67,7 +67,7 @@
"properties": {
"source_id": { "$ref": "#/definitions/SourceId" },
"model_id": { "type": "string", "minLength": 1 },
- "mode": { "enum": ["native", "executor", "direct"] },
+ "mode": { "enum": ["native", "executor", "service", "direct"] },
"at": { "$ref": "#/definitions/Moment" }
}
}
diff --git a/docs/plans/model-hub-contracts/mirror-registry.json b/docs/plans/model-hub-contracts/mirror-registry.json
index 72e5d0ddf..d79a68b48 100644
--- a/docs/plans/model-hub-contracts/mirror-registry.json
+++ b/docs/plans/model-hub-contracts/mirror-registry.json
@@ -1,5 +1,5 @@
{
- "contract_version": 18,
+ "contract_version": 19,
"input_generation": {
"mode": "same_run_live_files",
"external_snapshot": "content_fingerprint_required"
diff --git a/docs/plans/model-hub-contracts/observation-result.schema.json b/docs/plans/model-hub-contracts/observation-result.schema.json
index 3759c95c9..658187c58 100644
--- a/docs/plans/model-hub-contracts/observation-result.schema.json
+++ b/docs/plans/model-hub-contracts/observation-result.schema.json
@@ -16,7 +16,7 @@
],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 18 },
+ "contract_version": { "const": 19 },
"outcome": {
"enum": [
"observed",
@@ -150,7 +150,7 @@
],
"examples": [
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "observed",
"reachable": true,
"authenticated": "authenticated",
@@ -165,7 +165,7 @@
]
},
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "authentication_failed",
"reachable": true,
"authenticated": "rejected",
@@ -175,7 +175,7 @@
"model_metadata": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "ambiguous",
"reachable": true,
"authenticated": "unknown",
@@ -185,7 +185,7 @@
"model_metadata": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "unreachable",
"reachable": false,
"authenticated": "unknown",
@@ -195,7 +195,7 @@
"model_metadata": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "adapter_error",
"reachable": null,
"authenticated": "unknown",
@@ -205,7 +205,7 @@
"model_metadata": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "timeout",
"reachable": null,
"authenticated": "unknown",
diff --git a/docs/plans/model-hub-contracts/probe-result.schema.json b/docs/plans/model-hub-contracts/probe-result.schema.json
index abb8bb2ce..219b1a219 100644
--- a/docs/plans/model-hub-contracts/probe-result.schema.json
+++ b/docs/plans/model-hub-contracts/probe-result.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "backend", "channel", "reachable", "source_id", "model_id", "latency_ms", "error"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 18 },
+ "contract_version": { "const": 19 },
"backend": { "enum": ["claude", "codex", "opencode", "vibey"] },
"channel": { "enum": ["hub", "native_cli"] },
"reachable": { "type": "boolean" },
@@ -68,10 +68,10 @@
}
],
"examples": [
- { "contract_version": 18, "backend": "codex", "channel": "hub", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": 412, "error": null },
- { "contract_version": 18, "backend": "claude", "channel": "hub", "reachable": false, "source_id": "src_relay9c1x", "model_id": "glm-5.2", "latency_ms": 287, "error": "models.source.needs_action.balance_exhausted" },
- { "contract_version": 18, "backend": "codex", "channel": "hub", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.source.backoff.connection_failed" },
- { "contract_version": 18, "backend": "codex", "channel": "native_cli", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": null },
- { "contract_version": 18, "backend": "codex", "channel": "native_cli", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.probe.native_cli_unavailable" }
+ { "contract_version": 19, "backend": "codex", "channel": "hub", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": 412, "error": null },
+ { "contract_version": 19, "backend": "claude", "channel": "hub", "reachable": false, "source_id": "src_relay9c1x", "model_id": "glm-5.2", "latency_ms": 287, "error": "models.source.needs_action.balance_exhausted" },
+ { "contract_version": 19, "backend": "codex", "channel": "hub", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.source.backoff.connection_failed" },
+ { "contract_version": 19, "backend": "codex", "channel": "native_cli", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": null },
+ { "contract_version": 19, "backend": "codex", "channel": "native_cli", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.probe.native_cli_unavailable" }
]
}
diff --git a/docs/plans/model-hub-contracts/runtime-dependency.schema.json b/docs/plans/model-hub-contracts/runtime-dependency.schema.json
index 99f668294..90c90c12c 100644
--- a/docs/plans/model-hub-contracts/runtime-dependency.schema.json
+++ b/docs/plans/model-hub-contracts/runtime-dependency.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "manifest", "status"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 18 },
+ "contract_version": { "const": 19 },
"enabled": {
"type": "boolean",
"description": "Persisted user intent for the managed gateway. Fresh/default configuration is true; explicit stop persists false."
@@ -131,7 +131,7 @@
},
"examples": [
{
- "contract_version": 18,
+ "contract_version": 19,
"host_platform": "darwin-arm64",
"manifest": {
"name": "cliproxyapi",
diff --git a/docs/plans/model-hub-contracts/turn-provenance.schema.json b/docs/plans/model-hub-contracts/turn-provenance.schema.json
index 8e762b152..be82f1b65 100644
--- a/docs/plans/model-hub-contracts/turn-provenance.schema.json
+++ b/docs/plans/model-hub-contracts/turn-provenance.schema.json
@@ -36,7 +36,7 @@
"additionalProperties": false,
"properties": {
"contract_version": {
- "enum": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
+ "enum": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
"$comment": "The only versioned object written to disk, so released versions form a set rather than a constant. Historical records validate after the existing persistence-read normalization of retired reasons; tests/fixtures/model_hub/released_v5_permission_denied.json exercises that boundary, not raw-file validation. Reading preserves the writer generation and requires no new route fields. New records carry the terminal member. Other versioned objects are ephemeral envelopes pinned to that value alone.",
"description": "Generation that wrote this record. Readers retain every supported released value, apply existing retired-reason normalization independently of version, and do not require route_origin or manual_override."
},
@@ -487,7 +487,7 @@
],
"examples": [
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_01k9x2m4",
"ts": "2026-07-29T06:32:11Z",
"agent": "claude",
@@ -512,7 +512,7 @@
"blockers": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_01k9x33p",
"ts": "2026-07-29T06:41:02Z",
"agent": "opencode",
@@ -533,7 +533,7 @@
"blockers": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_01k9x3zq",
"ts": "2026-07-29T06:48:20Z",
"agent": "codex",
@@ -553,7 +553,7 @@
]
},
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_01k9x4b7",
"ts": "2026-07-29T07:02:44Z",
"agent": "claude",
@@ -573,7 +573,7 @@
"blockers": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_modelmissing01",
"ts": "2026-09-05T17:31:10Z",
"agent": "claude",
@@ -595,7 +595,7 @@
"blockers": []
},
{
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_01k9x5ca",
"ts": "2026-07-29T07:08:00Z",
"agent": "codex",
diff --git a/docs/plans/model-hub-contracts/usage-summary.schema.json b/docs/plans/model-hub-contracts/usage-summary.schema.json
index 858231d63..7b8c98f59 100644
--- a/docs/plans/model-hub-contracts/usage-summary.schema.json
+++ b/docs/plans/model-hub-contracts/usage-summary.schema.json
@@ -10,6 +10,7 @@
"to_day",
"totals",
"sources",
+ "services",
"days"
],
"oneOf": [
@@ -80,6 +81,13 @@
"$ref": "#/definitions/SourceUsage"
}
},
+ "services": {
+ "description": "One entry per (Source, search service) with at least one sent request in the window, busiest first. Service usage never appears in sources[].",
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/ServiceUsage"
+ }
+ },
"days": {
"description": "One entry per local day carrying a metered turn, oldest first. Hourly reports group the published bucket rows by bucket start date; daily reports retain local-calendar accounting.",
"type": "array",
@@ -190,10 +198,29 @@
"api_cost_lower_bound": {
"description": "True when api_cost_usd is only a floor: some tokens are excluded, some requests have no token report, or some priced usage was metered before cache writes were captured on a model that lists a cache-write price above input, or the read could not see all usage (a degraded ledger read, or an incomplete hourly bucket). Present exactly when `pricing` is.",
"type": "boolean"
+ },
+ "service_reported_usd": {
+ "description": "The sum of costs reported by search-service vendors, kept separate from the current-catalog list valuation. Present exactly when `pricing` is.",
+ "type": "number",
+ "minimum": 0
+ },
+ "excluded_service_requests": {
+ "$ref": "#/definitions/Count",
+ "description": "Billable search requests whose service has no current catalog price, so they are excluded from api_cost_usd. Present exactly when `pricing` is."
}
}
},
"UsageBucketRow": {
+ "oneOf": [
+ {
+ "$ref": "#/definitions/UsageModelBucketRow"
+ },
+ {
+ "$ref": "#/definitions/UsageServiceBucketRow"
+ }
+ ]
+ },
+ "UsageModelBucketRow": {
"type": "object",
"required": [
"source_id",
@@ -249,6 +276,53 @@
}
}
},
+ "UsageServiceBucketRow": {
+ "type": "object",
+ "required": [
+ "kind",
+ "source_id",
+ "service_id",
+ "requests",
+ "billable_requests",
+ "uncertain_requests",
+ "reported_requests"
+ ],
+ "additionalProperties": false,
+ "properties": {
+ "kind": {
+ "const": "service"
+ },
+ "source_id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "service_id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "billable_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "uncertain_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "reported_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "reported_usd": {
+ "$ref": "#/definitions/Counters/properties/service_reported_usd"
+ },
+ "api_cost_usd": {
+ "$ref": "#/definitions/Counters/properties/api_cost_usd"
+ },
+ "api_cost_lower_bound": {
+ "$ref": "#/definitions/Counters/properties/api_cost_lower_bound"
+ }
+ }
+ },
"UsageBucket": {
"type": "object",
"required": [
@@ -426,6 +500,76 @@
}
}
},
+ "ServiceUsage": {
+ "type": "object",
+ "required": [
+ "source_id",
+ "service_id",
+ "label",
+ "service_label",
+ "requests",
+ "billable_requests",
+ "uncertain_requests",
+ "reported_requests",
+ "last_metered_at"
+ ],
+ "additionalProperties": false,
+ "properties": {
+ "source_id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "service_id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "label": {
+ "description": "Current Source label, null once the Source is removed.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "service_label": {
+ "description": "Current catalog label, null when this service is no longer in the catalog.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "billable_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "uncertain_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "reported_requests": {
+ "$ref": "#/definitions/Count"
+ },
+ "last_metered_at": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "format": "date-time"
+ },
+ "priced": {
+ "type": "boolean"
+ },
+ "reported_usd": {
+ "$ref": "#/definitions/Counters/properties/service_reported_usd"
+ },
+ "api_cost_usd": {
+ "$ref": "#/definitions/Counters/properties/api_cost_usd"
+ },
+ "api_cost_lower_bound": {
+ "$ref": "#/definitions/Counters/properties/api_cost_lower_bound"
+ }
+ }
+ },
"DayUsage": {
"type": "object",
"required": [
@@ -473,11 +617,17 @@
},
"api_cost_lower_bound": {
"$ref": "#/definitions/Counters/properties/api_cost_lower_bound"
+ },
+ "service_reported_usd": {
+ "$ref": "#/definitions/Counters/properties/service_reported_usd"
+ },
+ "excluded_service_requests": {
+ "$ref": "#/definitions/Count"
}
}
},
"Pricing": {
- "description": "The price table the cost fields were computed from: models.dev list prices under the local override file. Absent from documents produced before API-price valuation existed, and whenever no price table could be read; the cost fields are then absent too.",
+ "description": "Current model price table and optional service-catalog verification date. Absent when no model table can be read; every cost field is then absent too.",
"type": "object",
"required": [
"currency",
@@ -502,6 +652,10 @@
"pending": {
"description": "Present (true) when no models.dev price table has been read yet and a first fetch is running that is expected to land; the cost fields then cover only what local overrides price. A client may re-read shortly and say prices are being fetched rather than that there are none. Absent means no fetch is awaited: a table is in hand, or the last fetch failed.",
"const": true
+ },
+ "service_price_date": {
+ "description": "Oldest catalog price verification date among the search services that were priced in this report.",
+ "$ref": "#/definitions/LocalDay"
}
}
}
@@ -524,6 +678,7 @@
"excluded_tokens": 0,
"api_cost_lower_bound": false
},
+ "services": [],
"sources": [
{
"source_id": "src_conform001",
diff --git a/docs/plans/web-search-services-s2a.md b/docs/plans/web-search-services-s2a.md
new file mode 100644
index 000000000..eeeb1d366
--- /dev/null
+++ b/docs/plans/web-search-services-s2a.md
@@ -0,0 +1,40 @@
+# Web search services S2a: readers before writers
+
+Source of truth: [web-search-services.md](web-search-services.md), especially §4.3,
+§6.5, §8 and §12. S2a is dormant: it accepts and renders the final service shapes
+but never searches, meters a live service request, writes service evidence, or
+changes `SEARCH_SERVICES_ACTIVE`. S2b owns those producers and activation.
+
+## Change contract
+
+- C-1 accepts optional attempts, estimated costs and a search-API executor origin;
+ released native/model records load and serialize unchanged. `HostedSource` and
+ the assistant's four-protocol `Origin` are unchanged.
+- When attempts are present, they alone own executor identity and the total.
+ Skips cost nothing; unknown tried charges make a known sum a lower bound;
+ nonzero list/estimated figures are approximate and an exact zero is not.
+ Current Source state governs remedies, never historical accounting.
+- The Web card and IM consume one projection, with localized switch and repair
+ notes; released model-only payloads remain byte-identical.
+- Service ledger quantities are independently identified and repaired on both
+ doors. Model counts never include service requests. Current catalog prices
+ value service quantities only when the existing model price table is present.
+- Usage has a separate service table and candidate-gated Source detail; removing
+ a Source/catalog row preserves the counts and reported amounts.
+- Evidence readers accept `service` without a live producer. Contract v19 is open for S2a; it remains dormant until S2b activates the producer.
+
+## Owning validation boundaries
+
+- C-1 schema/reader table: new service variants plus released load fixtures;
+ catches strict readers dropping new fields or narrowing released sources.
+- Hosted activity matrix plus shared Web fixtures: last tried role, skip-only,
+ zero/unknown/estimated/partial totals, switch, every blocked remedy and
+ supersession. Existing shared fixtures protect unchanged model payloads.
+- Ledger write/read and summary: repaired relations, released rows, removal,
+ catalog repricing, hourly/daily counts and pricing absence. Existing usage tests
+ protect retention and model accounting rather than duplicating them.
+- UI tests: shared card fixtures in both locales, Usage service rows, active and
+ dormant detail. Typecheck, lint and production build cover all consumers.
+
+Downgrade is the documented §12 boundary once S2b writes these shapes. S2a alone
+writes none from live paths; no migration, reset, deployment or public-doc change.
diff --git a/docs/plans/web-search-services.md b/docs/plans/web-search-services.md
index 38806ad1d..7030ac9c6 100644
--- a/docs/plans/web-search-services.md
+++ b/docs/plans/web-search-services.md
@@ -667,28 +667,15 @@ One coordinated Model Hub version event under the freeze protocol (`model-hub-co
| --- | --- | --- | --- |
| **S1a** Catalog and Sources | foundation | search vendors in the catalog; the Source UI guards for a `search` Source (no model refresh, test or add-model controls; its row says "搜索服务"); `protocol: "search"` Sources and their exclusions (the credential store accepts the protocol, the engine config renderer skips it); the protocol vocabulary split; the create and replace branch with free checks; "重新启用" (`reenable_search_source`, its free check and the armed-trial state); `service_order` maintenance on create and remove; the adapter's search call and free-check operation with custody and transport rules; opening the v17 version event | — |
| **S1b** Settings and Tools read | foundation | no service candidate and no `service_vendors` in the read until S2 activates them; `prefer_native`, `services` (the patch semantics and load-time clamping) and `executor_order_kinds` (loaded, written with each order save, and kept across a restart); the Tools read (`executor_candidates` with `kind`, `service_vendors`, `trial_pending`) and PUT; their v17 entries | S1a |
-| **S2** Chain and records | gateway | candidates, automatic order and the saved-order placement rule, limits, per-vendor request and result mapping with field bounds, outcome classes into fenced Source health, positive evidence, record with `attempts[]`, cost and metering, `prefer_native` in hop facts, the no-candidate reason, the `hosted_activity` projection and the card's executor label ("通过 Tavily", read from `attempts[]`) | S1a, S1b, S1c, S4, S6's disclosure |
+| **S2a** Chain readers and usage | readers | C-1 `attempts[]`, service executor origin, estimated cost and service error-code readers/writers; attempts-only hosted-activity projection and Web/IM rendering; service ledger and usage-summary readers plus the service-row write API; `mode: "service"` readers; released-shape fixtures and tests. Dormant: no chain, producer, metering call or activation. | S1a, S1b, S1c, S4 |
+| **S2b** Chain producer and activation | gateway | Candidate chain and order placement; adapter search calls and mapping; outcomes into health/cooldowns, trial gate, positive evidence and metering writes; hop facts and turn freeze; retry route; flips `SEARCH_SERVICES_ACTIVE`. | S2a, S6's disclosure |
| ~~S3~~ | — | cancelled 2026-10-20 with page content; the card's executor label ("通过 Tavily") moves to S2 with the projection | — |
| **S1c** Content removal | foundation | removes what S1a and S1b landed for page content: the catalog's content request mapping, `content_max_chars` and `page` price extras; S1b's `services.<id>.content` (a saved key is ignored on load), the read's `settings.content` and the vendor page-text flags, with `hosted-tools-status.schema.json`, `api.md`, the UI types and the v18 entries (v19 if a release has carried v18) | S1b |
| **S4** Tools, dialog, Sources | UI | §6 with en and zh copy, built against the read shape with fixtures; it shows service rows and the add dialog's services only when the read lists them | S1b's read shape as S1c leaves it; S5's frames |
| **S5** Frames | design | §6 frames in `design.pen` through Pencil (done: avibe-docs#73) | — |
| **S6** Public docs | docs | Models → Tools: services, order, defaults, privacy and cost, in English and Chinese. The disclosure part (an official DeepSeek Source joins the search order automatically, which data goes to each service, what it costs, and how to turn it off) publishes no later than the release that ships S2; the UI walkthrough follows S4 | the disclosure lands before or with S2 (S2 depends on it); the walkthrough follows S4 |
-The version event follows the v15 precedent in `model-hub-contracts/README.md`: S1a opens v17 and publishes the
-Source side, and S1b and S2 edit the same v17 section only while it is unshipped, as the hosted-tools
-freeze rule says (`vibey-hosted-tools.md` §12). A lane that lands after a release has carried v17 opens v18 for
-its additions instead, so a shipped version number never changes meaning. Because release
-candidates are cut from the default branch at any time, every lane is safe on its own until the event closes:
-before S2, a `search` Source is never requested and never affects model routing, discovery or engine config, and
-the shapes S1a and S1b write are final except for what S1c removes. S1c drops the page-content fields, and its
-loader ignores a `services.<id>.content` key that a pre-S1c build saved, so no migration write is needed. S4 and S2
-build on the post-S1c shape, so they read it without migration. No release turns on a new third-party data flow before
-it is disclosed: S2's release carries S6's disclosure and a release note naming DeepSeek's automatic enrolment and
-how to turn it off (the `services.<id>.enabled` switch, available through S1b's PUT). S2 is the activation lane: on its head the
-read starts listing service candidates and `service_vendors` and the chain starts calling services, and S4
-lands before it, so the release that turns services on has the service rows, the add dialog and the
-disclosure. Before S2, no surface shows a service the gateway cannot run, and a `search` Source can only be created
-through the API.
+The version event follows the v15 precedent in `model-hub-contracts/README.md`: S1a opened v17, S1b/S1c completed v18, and RC tag `gh-v3.2.2rc13` carries v18. S2a therefore opens v19 for reader and usage shapes; S2b may share v19 while it is unshipped, otherwise it opens v20. Before S2b, S2a is dormant and safe to release: it adds no producer, third-party request or activation. S1c's compatibility rule for removed page-content fields remains in force. S2b's activation release carries S6's disclosure, and the freeze rule means a shipped version never changes meaning.
## 10. Acceptance properties
@@ -736,7 +723,8 @@ Hermetic, against stub vendor servers; no live upstream and no real keys.
older release's strict reader rejects, so that Session no longer loads there;
- any sent service request, which writes a service-shaped usage ledger row even when the call was stopped and
left no record. An older reader requires `model_id` and drops that row, so after a downgrade the Usage tab
- loses that service usage; model usage is unaffected;
+ loses that service usage; model rows remain, but the lost service rows mark the surviving usage history as
+ degraded or lower-bound, and hourly history is incomplete until the affected evidence ages out;
- a completed service attempt's capability evidence (`mode: "service"`), which an older reader skips and its next
evidence write prunes, so after a downgrade the Tools status loses its latest successful service.
diff --git a/modules/agents/vibey/agent.py b/modules/agents/vibey/agent.py
index 3c2e63ade..ab40861c2 100644
--- a/modules/agents/vibey/agent.py
+++ b/modules/agents/vibey/agent.py
@@ -1633,24 +1633,42 @@ class VibeyAgent(BaseAgent):
except Exception:
logger.exception("Vibey could not deliver %d generated image(s)", len(run.hosted_images))
- async def _source_names(self) -> Mapping[str, str]:
- """Each Model Hub Source's display name by id, as Model Hub holds them now.
+ async def _source_display(self) -> tuple[Mapping[str, str], Optional[Mapping[str, Mapping[str, Any]]]]:
+ """Each Model Hub Source's display name and current state by id, as Model Hub holds them now.
- Read through the Model Hub runtime, the one owner of its current config, off
- the event loop: ``self.config`` is the controller's app config, which carries
- no Model Hub state, and a Source renamed or added since start must show as it
- is now.
+ Read through the Model Hub runtime, the one owner of its current config, off the event loop: ``self.config``
+ is the controller's app config, which carries no Model Hub state, and a Source renamed, repaired, turned off
+ for search or removed since must show as it is now (``core.hosted_activity.SourceState``). Without a read
+ the states are None, so a card offers no repair it could not check.
"""
runtime = getattr(self.controller, "model_hub_runtime", None)
if runtime is None:
- return {}
+ return {}, None
+
+ def read() -> tuple[dict[str, str], dict[str, dict[str, Any]]]:
+ from config.v2_config import hosted_tool_setting
+ from core.handlers.model_hub.hosted_tools import search_service_settings
+
+ hub = runtime.snapshot()
+ web_search = hosted_tool_setting(hub, "web_search")
+ names = {source.id: source.display_name for source in hub.sources if source.display_name}
+ states: dict[str, dict[str, Any]] = {}
+ for source in hub.sources:
+ state: dict[str, Any] = {"protocol": source.protocol, "vendor": source.vendor}
+ if source.state.status in ("needs_action", "error"):
+ state["needs_action"] = source.state.detail_key
+ service = search_service_settings(web_search, source)
+ if service is not None:
+ state["enabled"] = service["enabled"]
+ states[source.id] = state
+ return names, states
+
try:
- hub = await asyncio.to_thread(runtime.snapshot)
+ return await asyncio.to_thread(read)
except Exception:
- # A name is display only: the card and the line still show the Source by id.
- logger.warning("Vibey could not read Model Hub's Sources for display names", exc_info=True)
- return {}
- return {source.id: source.display_name for source in hub.sources if source.display_name}
+ # Display only: the card and the line still show each Source by its id or the label it was recorded with.
+ logger.warning("Vibey could not read Model Hub's Sources for display", exc_info=True)
+ return {}, None
async def _emit_hosted(self, run: _Run, activity: HostedActivity) -> None:
"""One hosted call: its line for IM and its card for the Web (``core.hosted_activity``)."""
@@ -1674,7 +1692,7 @@ class VibeyAgent(BaseAgent):
message = run.responses.get(row_id)
if message is None:
return
- names = await self._source_names()
+ names, _states = await self._source_display()
for activity in native_activities(message, source_names=names.get, response_id=row_id):
await self._emit_hosted(run, activity)
@@ -1695,8 +1713,17 @@ class VibeyAgent(BaseAgent):
await self._emit_tool_line(run, call.name, dict(call.arguments))
return
duration = int((time.monotonic() - started) * 1000) if started is not None else None
- names = await self._source_names()
- await self._emit_hosted(run, proxy_activity(call, result.hosted, source_names=names.get, duration_ms=duration))
+ names, states = await self._source_display()
+ await self._emit_hosted(
+ run,
+ proxy_activity(
+ call,
+ result.hosted,
+ source_names=names.get,
+ source_state=states.get if states is not None else None,
+ duration_ms=duration,
+ ),
+ )
def _committed_tool_result(self, event_id: str) -> Optional[ToolResultMessage]:
"""The tool result a ``ToolFinished`` names: one row, by primary key."""
diff --git a/tests/agent_core/fixtures/released_hosted_messages.json b/tests/agent_core/fixtures/released_hosted_messages.json
new file mode 100644
index 000000000..89a5a3133
--- /dev/null
+++ b/tests/agent_core/fixtures/released_hosted_messages.json
@@ -0,0 +1,16 @@
+[
+ {
+ "role": "assistant",
+ "content": [{"type": "hosted_tool", "id": "search_1", "tool": "web_search", "action": {"type": "search", "queries": ["Avibe"]}, "record": {"status": "completed", "sources": [{"url": "https://avibe.bot", "title": "Avibe", "snippet": "A local-first Agent OS", "page_age": "yesterday"}]}, "native": {"source_id": "src_released01", "payload": [{"type": "web_search_call", "status": "completed"}]}}],
+ "origin": {"provider": "openai", "api": "openai_responses", "model": "gpt-5.5"},
+ "stop_reason": "stop",
+ "hosted_summary": {"counts": {"web_search_calls": 1}, "cited_sources": [], "cost": {"basis": "list", "usd": 0.01}}
+ },
+ {
+ "role": "tool_result", "tool_call_id": "call_1", "tool_name": "web_search", "content": [{"type": "text", "text": "1. Avibe — https://avibe.bot"}], "is_error": false,
+ "hosted": {
+ "record": {"status": "completed", "sources": [{"url": "https://avibe.bot"}]},
+ "execution": {"mode": "proxy", "executor_origin": {"provider": "anthropic", "api": "anthropic", "model": "claude-haiku-5-5"}, "executor_source_id": "src_released01", "executor_billing": "metered", "cost": {"basis": "reported", "usd": 0.008}, "failed_attempts": [{"source_id": "src_released02", "billing": "metered"}]}
+ }
+ }
+]
diff --git a/tests/agent_core/test_hosted_messages.py b/tests/agent_core/test_hosted_messages.py
index 98cbc2b20..cba111461 100644
--- a/tests/agent_core/test_hosted_messages.py
+++ b/tests/agent_core/test_hosted_messages.py
@@ -363,6 +363,45 @@ def test_a_generate_action_names_a_prompt_only_when_the_endpoint_revised_it(payl
assert message_from_dict(payload).hosted.action.prompt is None
+ "payload",
+ json.loads((Path(__file__).parent / "fixtures/released_hosted_messages.json").read_text()),
+ ids=["released-native", "released-model-executor"],
+)
+def test_released_hosted_rows_load_unchanged_without_service_fields(payload):
+ """S2a: optional service fields cannot make a released transcript unreadable."""
+ VALIDATOR.validate(payload)
+ assert message_to_dict(message_from_dict(payload)) == payload
+ # Service result-mapping limits must not narrow the released C-1 source shape.
+ long_source = {"url": "https://a.test/" + "u" * 2048, "title": "t" * 301,
+ "snippet": "s" * 1001, "page_age": "p" * 65}
+ expanded = copy.deepcopy(payload)
+ record = expanded["content"][0]["record"] if payload["role"] == "assistant" else expanded["hosted"]["record"]
+ record["sources"] = [long_source]
+ VALIDATOR.validate(expanded)
+ assert message_to_dict(message_from_dict(expanded)) == expanded
+
+
[email protected]("outcome", ["completed", "failed", "skipped"])
+def test_service_attempts_and_origin_load_and_round_trip(outcome):
+ """S2a: the new writer shape is accepted by both strict persisted readers."""
+ payload = copy.deepcopy(PROXIED)
+ payload["tool_name"] = "web_search"
+ payload["hosted"]["execution"]["executor_origin"] = {
+ "provider": "exa", "api": "search_api", "model": "exa/search",
+ }
+ attempt = {"source_id": SOURCE, "label": "Exa", "kind": "service", "outcome": outcome}
+ if outcome == "skipped":
+ attempt.update(skipped="cooling", retry_at="2026-10-20T12:00:00Z")
+ else:
+ attempt["cost"] = {"basis": "reported", "usd": 0.007, "estimate": True}
+ if outcome == "failed":
+ attempt.update(error_code="service_unreadable", superseded=True)
+ payload["hosted"]["record"]["attempts"] = [attempt]
+ VALIDATOR.validate(payload)
+ assert message_to_dict(message_from_dict(payload)) == payload
+
+
def test_a_citation_range_must_lie_within_its_text():
# The schema cannot compare a range with the text length; the producer and reader own it.
with pytest.raises(ValueError):
diff --git a/tests/e2e/test_model_hub_runtime.py b/tests/e2e/test_model_hub_runtime.py
index 32c902b3e..648daa666 100644
--- a/tests/e2e/test_model_hub_runtime.py
+++ b/tests/e2e/test_model_hub_runtime.py
@@ -684,7 +684,7 @@ def test_a1_feature_flag_disables_the_complete_models_api(
assert response.status == 404, (method, path, body)
assert body == {
"ok": False,
- "contract_version": 18,
+ "contract_version": 19,
"error": "feature_disabled",
}
diff --git a/tests/e2e/test_model_hub_sources.py b/tests/e2e/test_model_hub_sources.py
index c0ff7a2cc..bd3da094e 100644
--- a/tests/e2e/test_model_hub_sources.py
+++ b/tests/e2e/test_model_hub_sources.py
@@ -13,7 +13,7 @@ from tests.e2e.drivers.mock_llm_upstream import MockLLMUpstream
pytestmark = pytest.mark.e2e_model_hub
-CONTRACT_VERSION = 18
+CONTRACT_VERSION = 19
MENU_MODEL = "claude-sonnet-4-6"
SYNTHETIC_API_KEY = "sk-model-hub-e2e-not-real"
diff --git a/tests/test_hosted_activity.py b/tests/test_hosted_activity.py
index e09db2f69..fdebb29e3 100644
--- a/tests/test_hosted_activity.py
+++ b/tests/test_hosted_activity.py
@@ -14,9 +14,11 @@ import pytest
from core.agent_core.messages import (
HOSTED_ERROR_CODES,
+ HOSTED_SKIP_REASONS,
AssistantMessage,
FailedAttempt,
HostedAction,
+ HostedAttempt,
HostedCost,
HostedFallback,
HostedImage,
@@ -28,6 +30,7 @@ from core.agent_core.messages import (
HostedToolBlock,
Origin,
ProxyExecution,
+ ServiceExecutorOrigin,
TextBlock,
ToolCallBlock,
)
@@ -277,6 +280,8 @@ def test_a_response_scoped_summary_is_shown_once():
# Only the X search without per-call results shows the response's cited posts.
assert [a.sources for a in activities] == [(DEVDAY,), POSTS, ()]
assert activities[0].extra_queries == ("grok 5 benchmarks",)
+ # The card lists them as "Also searched".
+ assert activities[0].to_payload()["extra_queries"] == ["grok 5 benchmarks"]
assert activities[1].subject == "from:xai"
@@ -434,12 +439,32 @@ def _slots(text: str):
"executor model": replace(proxy_x_search(), model=text),
"image model": replace(direct_image(), model=text),
"compatible endpoint": replace(native_web_search(), provider="custom", source_name=text),
+ "switched-from source": _chain(
+ (_tried(TAVILY, error_code="service_key_invalid", usd=0.0), _tried(DEEPSEEK, "completed", usd=0.0)),
+ execution=_service_ran(DEEPSEEK, "deepseek"),
+ names={TAVILY: text, DEEPSEEK: "DeepSeek"},
+ state=_now({TAVILY: {"needs_action": KEY}}),
+ ),
+ "repaired source": _chain(
+ (_skip(TAVILY, "blocked", needs_action=KEY),), status="failed", names={TAVILY: text},
+ state=_now({TAVILY: {"needs_action": KEY}}),
+ ),
}
@pytest.mark.parametrize("text", HOSTILE)
@pytest.mark.parametrize(
- "slot", ["subject", "error", "fallback source", "executor model", "image model", "compatible endpoint"],
+ "slot",
+ [
+ "subject",
+ "error",
+ "fallback source",
+ "executor model",
+ "image model",
+ "compatible endpoint",
+ "switched-from source",
+ "repaired source",
+ ],
)
def test_the_im_line_leaves_no_mention_or_masked_link_live_in_untrusted_text(slot, text):
"""MH-HOSTED-UI-010: a query, a provider's error, and a user's Source or model name are not Avibe's words. The
@@ -494,3 +519,400 @@ def test_every_known_hosted_error_code_has_copy_on_every_surface(code):
hosted = json.loads((UI_BUNDLES / f"{lang}.json").read_text(encoding="utf-8"))["chat"]["agentActivity"]["hosted"]
assert hosted.get("errorCode", {}).get(code), f"ui/src/i18n/{lang}.json has no chat.agentActivity.hosted.errorCode.{code}"
+
+# A search chain with search-capable candidates (web-search-services.md §4.3, §6.5). The cards are pinned to
+# ``ui/src/lib/hostedServiceActivity.fixture.json``, which the Web card tests render in both languages.
+SERVICE_FIXTURE = json.loads(
+ (Path(__file__).resolve().parents[1] / "ui/src/lib/hostedServiceActivity.fixture.json").read_text(encoding="utf-8")
+)
+TAVILY, EXA, DEEPSEEK, CLAUDE = "src_tavily01", "src_exa00001", "src_deepseek1", "src_claude001"
+LABELS = {TAVILY: "Tavily", EXA: "Exa", DEEPSEEK: "DeepSeek", CLAUDE: "Anthropic API key"}
+NEEDS = "models.source.needs_action."
+KEY, BALANCE, LIMIT = f"{NEEDS}credential_revoked", f"{NEEDS}balance_exhausted", f"{NEEDS}spend_limit_reached"
+# Each Source as Model Hub holds it now, healthy; a test changes what it needs.
+HEALTHY = {
+ TAVILY: {"protocol": "search", "vendor": "tavily", "enabled": True},
+ EXA: {"protocol": "search", "vendor": "exa", "enabled": True},
+ DEEPSEEK: {"protocol": "openai_chat", "vendor": "deepseek", "enabled": True},
+ CLAUDE: {"protocol": "anthropic", "vendor": "anthropic"},
+}
+#: Model Hub could not be read when the card was drawn.
+UNREAD = None
+RESULTS = (
+ HostedSource(
+ url="https://api-docs.deepseek.com/guides/search-tool",
+ title="Search tool",
+ snippet="One HTTPS request returns ranked results.",
+ ),
+ HostedSource(url="https://api-docs.deepseek.com/quick_start/pricing", title="Models & Pricing"),
+ HostedSource(url="https://www.tavily.com/pricing", title="Tavily pricing"),
+ HostedSource(url="https://exa.ai/pricing", title="Exa pricing"),
+ HostedSource(
+ url="https://news.example.com/deepseek-search", title="DeepSeek adds a search API", page_age="2 days ago"
+ ),
+)
+CLAUDE_RAN = ProxyExecution(
+ executor_origin=Origin(provider="anthropic", api="anthropic", model="claude-haiku-5-5"),
+ executor_source_id=CLAUDE,
+ executor_billing="metered",
+ cost=HostedCost(basis="list", usd=0.01),
+)
+
+
+def _now(changes: dict) -> dict:
+ """The Sources now: ``{TAVILY: {"needs_action": KEY}}`` changes one, ``{EXA: None}`` removes it."""
+ current = {source_id: dict(state) for source_id, state in HEALTHY.items()}
+ for source_id, change in changes.items():
+ if change is None:
+ del current[source_id]
+ else:
+ current[source_id].update(change)
+ return current
+
+
+def _tried(source_id, outcome="failed", *, kind="service", usd=None, basis="list", estimate=None, **facts):
+ cost = HostedCost(basis=basis) if basis == "included" else (
+ HostedCost(basis=basis, usd=usd, estimate=estimate) if usd is not None else None
+ )
+ return HostedAttempt(source_id=source_id, label=LABELS[source_id], kind=kind, outcome=outcome, cost=cost, **facts)
+
+
+def _skip(source_id, reason, *, kind="service", **facts):
+ return HostedAttempt(
+ source_id=source_id, label=LABELS[source_id], kind=kind, outcome="skipped", skipped=reason, **facts
+ )
+
+
+def _service_ran(source_id, vendor, usd=None):
+ return ProxyExecution(
+ executor_origin=ServiceExecutorOrigin(provider=vendor, api="search_api", model=f"{vendor}/search"),
+ executor_source_id=source_id,
+ executor_billing="metered",
+ cost=HostedCost(basis="list", usd=usd) if usd is not None else None,
+ )
+
+
+def _chain(attempts, *, status="completed", execution=None, state=HEALTHY, names=LABELS, sources=(), call_id="call_ws",
+ error=None, error_code=None):
+ record = HostedRecord(
+ status=status,
+ error=error or (None if status == "completed" else "the search failed"),
+ error_code=error_code,
+ sources=sources,
+ attempts=attempts,
+ )
+ return proxy_activity(
+ ToolCallBlock(id=call_id, name="web_search", arguments={"query": "DeepSeek search API pricing"}),
+ HostedResult(record=record, execution=execution),
+ source_names=names.get,
+ source_state=state.get if state is not None else None,
+ )
+
+
+SERVICE_CARDS = {
+ # Design example: Tavily answers with five results.
+ "service_completed": lambda: _chain(
+ (_tried(TAVILY, "completed", usd=0.008),),
+ execution=_service_ran(TAVILY, "tavily", 0.008),
+ sources=RESULTS,
+ call_id="call_ws1",
+ ),
+ # Tavily answers 401, so its Source needs a new key, and DeepSeek answers in the same call.
+ "service_switch": lambda: _chain(
+ (_tried(TAVILY, error_code="service_key_invalid", usd=0.0), _tried(DEEPSEEK, "completed", usd=0.00075)),
+ execution=_service_ran(DEEPSEEK, "deepseek", 0.00075),
+ state=_now({TAVILY: {"needs_action": KEY}}),
+ sources=RESULTS,
+ call_id="call_ws2",
+ ),
+ # Tavily is cooling down, which is no failure of its own; Exa prices the request with its own estimate.
+ "service_estimate": lambda: _chain(
+ (
+ _skip(TAVILY, "cooling", retry_at="2026-10-21T04:30:00Z"),
+ _tried(EXA, "completed", basis="reported", usd=0.008, estimate=True),
+ ),
+ execution=_service_ran(EXA, "exa"),
+ sources=RESULTS,
+ call_id="call_ws3",
+ ),
+ # Two Sources blocked and the one tried unavailable before it sent anything: the blocked ones decide the reason.
+ "service_blocked": lambda: _chain(
+ (
+ _skip(TAVILY, "blocked", needs_action=KEY),
+ _skip(EXA, "blocked", needs_action=BALANCE),
+ _tried(DEEPSEEK, error_code="service_unavailable", usd=0.0),
+ ),
+ status="failed",
+ error="every search source is blocked or turned off",
+ error_code="search_sources_blocked",
+ state=_now({TAVILY: {"needs_action": KEY}, EXA: {"needs_action": BALANCE}}),
+ call_id="call_ws4",
+ ),
+}
+
+
[email protected]("case", SERVICE_CARDS)
+def test_a_search_services_card_and_line_say_the_same_in_both_languages(case):
+ """MH-HOSTED-UI-009, MH-HOSTED-UI-010: the card the Web renders from the shared fixture, and the IM line, from
+ the records a search chain writes and its Sources' current state. The switch and repair notes are the very
+ sentences the Web card shows."""
+
+ activity = SERVICE_CARDS[case]()
+ assert activity.to_payload() == SERVICE_FIXTURE[case]["payload"]
+ for lang in ("en", "zh"):
+ assert hosted_line(activity, lang) == SERVICE_FIXTURE[case][lang]["line"]
+
+
+ ("attempts", "execution", "status", "ran", "cost", "line_tail"),
+ [
+ pytest.param(
+ (_tried(TAVILY, "completed", usd=0.008),), _service_ran(TAVILY, "tavily", 0.008), "completed",
+ {"executor_kind": "service", "source_id": TAVILY, "source_name": "Tavily", "provider": "tavily"},
+ {"basis": "list", "usd": 0.008, "calls": 1}, "≈ $0.008",
+ id="a service, named as its Source, never by its service id",
+ ),
+ pytest.param(
+ (_tried(TAVILY, error_code="service_unavailable", usd=0.0),
+ _tried(CLAUDE, "completed", kind="model", usd=0.01)),
+ CLAUDE_RAN, "completed",
+ {"executor_kind": "model", "source_id": CLAUDE, "source_name": "Anthropic API key", "provider": "anthropic",
+ "model": "claude-haiku-5-5"},
+ {"basis": "list", "usd": 0.01, "calls": 1}, "≈ $0.01",
+ id="a model executor last: its execution adds the model the entry does not store",
+ ),
+ pytest.param(
+ (_tried(CLAUDE, "completed", kind="model", usd=0.01),), XAI, "completed",
+ {"executor_kind": "model", "source_id": CLAUDE, "source_name": "Anthropic API key"},
+ {"basis": "list", "usd": 0.01, "calls": 1}, "≈ $0.01",
+ id="an execution of another Source adds nothing",
+ ),
+ pytest.param(
+ (_skip(TAVILY, "blocked", needs_action=KEY), _skip(EXA, "disabled")), _service_ran(TAVILY, "tavily", 0.008),
+ "failed", {}, None, None,
+ id="nothing tried: a stale execution names no executor and no cost",
+ ),
+ pytest.param(
+ (_tried(CLAUDE, kind="model", error_code="provider_timed_out", usd=0.01),
+ _tried(TAVILY, error_code="service_unavailable", usd=0.0)),
+ None, "failed", {"executor_kind": "service", "source_id": TAVILY, "source_name": "Tavily"},
+ {"basis": "list", "usd": 0.01, "calls": 1}, "≈ $0.01",
+ id="a pre-send $0 after a billed model keeps the model's charge",
+ ),
+ pytest.param(
+ (_tried(DEEPSEEK, error_code="service_unreadable"),), None, "failed",
+ {"executor_kind": "service", "source_id": DEEPSEEK, "source_name": "DeepSeek"}, None, None,
+ id="every tried charge unknown: no cost",
+ ),
+ pytest.param(
+ (_tried(TAVILY, error_code="service_unreadable", usd=0.008),
+ _tried(DEEPSEEK, error_code="service_unreadable")),
+ None, "failed", {"executor_kind": "service", "source_id": DEEPSEEK, "source_name": "DeepSeek"},
+ {"basis": "list", "usd": 0.008, "calls": 1, "at_least": True}, "at least ≈ $0.008",
+ id="a known total beside an unknown charge is a lower bound",
+ ),
+ pytest.param(
+ (_skip(TAVILY, "cooling", retry_at="2026-10-21T04:30:00Z"),
+ _tried(CLAUDE, "completed", kind="model", basis="included")),
+ replace(CLAUDE_RAN, executor_billing="monthly", cost=HostedCost(basis="included")), "completed",
+ {"executor_kind": "model", "source_id": CLAUDE, "source_name": "Anthropic API key", "provider": "anthropic",
+ "model": "claude-haiku-5-5"},
+ {"basis": "included", "calls": 1}, "included in subscription",
+ id="a skip sent nothing and never makes a total a lower bound",
+ ),
+ pytest.param(
+ (_tried(TAVILY, error_code="service_unavailable", usd=0.0),
+ _tried(EXA, "completed", basis="reported", usd=0.005)),
+ _service_ran(EXA, "exa"), "completed",
+ {"executor_kind": "service", "source_id": EXA, "source_name": "Exa", "provider": "exa"},
+ {"basis": "reported", "usd": 0.005, "calls": 1}, "$0.005",
+ id="an exact $0 beside an exact reported figure is not approximate",
+ ),
+ pytest.param(
+ (_tried(EXA, "completed", basis="reported", usd=0.008, estimate=True),), _service_ran(EXA, "exa"), "completed",
+ {"executor_kind": "service", "source_id": EXA, "source_name": "Exa", "provider": "exa"},
+ {"basis": "reported", "usd": 0.008, "calls": 1, "estimate": True}, "≈ $0.008",
+ id="a vendor's estimate is approximate",
+ ),
+ pytest.param(
+ (_tried(DEEPSEEK, "completed", usd=0.0),), _service_ran(DEEPSEEK, "deepseek", 0.0), "completed",
+ {"executor_kind": "service", "source_id": DEEPSEEK, "source_name": "DeepSeek", "provider": "deepseek"},
+ {"basis": "list", "usd": 0, "calls": 1}, "$0",
+ id="an exact zero is never an estimate",
+ ),
+ pytest.param(
+ None, _service_ran(TAVILY, "tavily", 0.008), "completed",
+ {"executor_kind": "service", "source_id": TAVILY, "source_name": "Tavily", "provider": "tavily"},
+ {"basis": "list", "usd": 0.008, "calls": 1}, "≈ $0.008",
+ id="without attempts, a search_api origin is still a service",
+ ),
+ ],
+)
+def test_a_search_chain_alone_says_who_ran_it_and_what_it_cost(attempts, execution, status, ran, cost, line_tail):
+ """§4.3: with ``attempts``, the last tried entry ran the call and the tried entries' costs are its total; a skip
+ sent nothing. ``execution`` keeps its released meaning for older readers and lends only its model, and only to
+ the entry it names."""
+
+ activity = _chain(attempts, status=status, execution=execution, sources=RESULTS[:1] if status == "completed" else ())
+ payload = activity.to_payload()
+ named = ("executor_kind", "source_id", "source_name", "provider", "model")
+ assert {key: payload[key] for key in named if key in payload} == ran
+ assert payload.get("cost") == cost
+ line = hosted_line(activity, "en")
+ assert line.endswith(f" · {line_tail}") if line_tail else "$" not in line
+
+
+ ("attempt", "state", "shown"),
+ [
+ # Blocked: the skip stays as recorded, and the Source's current health chooses its repair.
+ pytest.param(_skip(TAVILY, "blocked", needs_action=KEY), _now({TAVILY: {"needs_action": KEY}}),
+ ("reason.service_key_invalid", "repair.key", None), id="blocked: replace the key"),
+ pytest.param(_skip(CLAUDE, "blocked", kind="model", needs_action=f"{NEEDS}oauth_expired"),
+ _now({CLAUDE: {"needs_action": f"{NEEDS}oauth_expired"}}),
+ ("skip.blocked", "repair.reauthorize", None), id="blocked: sign in again"),
+ pytest.param(_skip(EXA, "blocked", needs_action=BALANCE), _now({EXA: {"needs_action": BALANCE}}),
+ ("reason.service_balance", "repair.balanceReenable", None),
+ id="blocked search Source: top up, re-enable"),
+ pytest.param(_skip(DEEPSEEK, "blocked", needs_action=BALANCE), _now({DEEPSEEK: {"needs_action": BALANCE}}),
+ ("reason.service_balance", "repair.balance", None), id="blocked model Source: top up only"),
+ pytest.param(_skip(EXA, "blocked", needs_action=LIMIT), _now({EXA: {"needs_action": LIMIT}}),
+ ("reason.service_limit", "repair.limitReenable", None),
+ id="blocked search Source: raise the limit, re-enable"),
+ pytest.param(_skip(TAVILY, "blocked", needs_action=LIMIT), _now({TAVILY: {"needs_action": LIMIT}}),
+ ("reason.service_limit", "repair.tavilyLimit", None), id="Tavily: both of its limits"),
+ pytest.param(_skip(CLAUDE, "blocked", kind="model", needs_action=f"{NEEDS}plan_excludes_product"),
+ _now({CLAUDE: {"needs_action": f"{NEEDS}plan_excludes_product"}}),
+ ("skip.blocked", "repair.plan", None), id="blocked: change the plan"),
+ pytest.param(_skip(CLAUDE, "blocked", kind="model", needs_action=f"{NEEDS}account_banned"),
+ _now({CLAUDE: {"needs_action": f"{NEEDS}account_banned"}}),
+ ("skip.blocked", "repair.account", None), id="blocked: restore the account"),
+ pytest.param(_skip(CLAUDE, "blocked", kind="model", needs_action="models.source.error.unclassified"),
+ _now({CLAUDE: {"needs_action": "models.source.error.unclassified"}}),
+ ("skip.blocked", "repair.error", None), id="blocked: a persistent error"),
+ pytest.param(_skip(TAVILY, "blocked", needs_action=KEY), _now({TAVILY: {"needs_action": BALANCE}}),
+ ("reason.service_key_invalid", "repair.balanceReenable", None),
+ id="blocked, needing something else now"),
+ pytest.param(_skip(TAVILY, "blocked", needs_action=KEY), HEALTHY,
+ ("reason.service_key_invalid", None, None), id="blocked, repaired since"),
+ pytest.param(_skip(TAVILY, "blocked", needs_action=KEY), _now({TAVILY: None}),
+ ("reason.service_key_invalid", None, None), id="blocked, removed since"),
+ pytest.param(_skip(TAVILY, "blocked", needs_action=KEY), UNREAD,
+ ("reason.service_key_invalid", None, None), id="blocked, Model Hub unread"),
+ # Disabled: the remedy is turning search back on, while it is still off.
+ pytest.param(_skip(EXA, "disabled"), _now({EXA: {"enabled": False}}),
+ ("skip.disabled", "repair.disabled", None), id="disabled, still off"),
+ pytest.param(_skip(EXA, "disabled"), HEALTHY, ("skip.disabled", None, None), id="disabled, turned on since"),
+ pytest.param(_skip(EXA, "disabled"), _now({EXA: None}), ("skip.disabled", None, None), id="disabled, removed since"),
+ # Failed: the health its code set must still be the Source's, or a later action has superseded it.
+ pytest.param(_tried(TAVILY, error_code="service_key_invalid", usd=0.0), _now({TAVILY: {"needs_action": KEY}}),
+ ("reason.service_key_invalid", "repair.key", None), id="failed: the health its code set"),
+ pytest.param(_tried(TAVILY, error_code="service_limit", usd=0.0), _now({TAVILY: {"needs_action": LIMIT}}),
+ ("reason.service_limit", "repair.tavilyLimit", None), id="failed at Tavily's limit"),
+ pytest.param(_tried(DEEPSEEK, error_code="service_balance", usd=0.0), _now({DEEPSEEK: {"needs_action": BALANCE}}),
+ ("reason.service_balance", "repair.balance", None), id="failed: a model Source's balance"),
+ pytest.param(_tried(TAVILY, error_code="service_key_invalid", usd=0.0, superseded=True),
+ _now({TAVILY: {"needs_action": KEY}}), ("reason.superseded", None, True), id="superseded by a fence"),
+ pytest.param(_tried(TAVILY, error_code="service_key_invalid", usd=0.0), HEALTHY,
+ ("reason.superseded", None, True), id="superseded: the key was replaced"),
+ pytest.param(_tried(TAVILY, error_code="service_balance", usd=0.0), _now({TAVILY: {"needs_action": KEY}}),
+ ("reason.superseded", None, True), id="superseded: a later failure set other health"),
+ pytest.param(_tried(TAVILY, error_code="service_unavailable", usd=0.0), _now({TAVILY: None}),
+ ("reason.superseded", None, True), id="superseded: the Source was removed"),
+ pytest.param(_tried(TAVILY, error_code="service_key_invalid", usd=0.0), UNREAD,
+ ("reason.service_key_invalid", None, None), id="failed, Model Hub unread: no repair"),
+ pytest.param(_tried(TAVILY, error_code="service_unavailable", usd=0.0), _now({TAVILY: {"needs_action": KEY}}),
+ ("reason.service_unavailable", None, None), id="a transient failure set no health"),
+ pytest.param(_tried(CLAUDE, kind="model", error_code="provider_timed_out", usd=0.01), HEALTHY,
+ ("reason.failed", None, None), id="a model executor's failure"),
+ pytest.param(_tried(CLAUDE, kind="model", usd=0.01), HEALTHY, ("reason.failed", None, None),
+ id="a model executor's failure without a code"),
+ # Skips that are no failure of the Source's own, and need nothing.
+ pytest.param(_skip(TAVILY, "cooling", retry_at="2026-10-21T04:30:00Z"), HEALTHY,
+ ("skip.cooling", None, None), id="cooling"),
+ pytest.param(_skip(DEEPSEEK, "query_too_long"), HEALTHY, ("skip.query_too_long", None, None), id="query too long"),
+ pytest.param(_skip(TAVILY, "unavailable"), _now({TAVILY: None}), ("skip.unavailable", None, None), id="unavailable"),
+ ],
+)
+def test_each_source_a_chain_reached_shows_what_it_needs_now(attempt, state, shown):
+ """§4.3: the record keeps what happened; the Source's current state decides the repair and whether a failure
+ still stands, once, for the card and the IM line alike. A Source repaired, re-enabled or removed since shows no
+ repair, and without a Model Hub read none is offered."""
+
+ [entry] = _chain((attempt,), status="failed", state=state).attempts
+ assert (entry.reason_key, entry.remedy_key, entry.superseded) == shown
+ assert (entry.outcome, entry.skipped, entry.needs_action, entry.error_code, entry.cost) == (
+ attempt.outcome, attempt.skipped, attempt.needs_action, attempt.error_code, attempt.cost
+ )
+
+
+ ("attempts", "names", "state", "switch", "notes"),
+ [
+ pytest.param(
+ (_tried(TAVILY, error_code="service_key_invalid", usd=0.0), _tried(DEEPSEEK, "completed", usd=0.0)), LABELS,
+ _now({TAVILY: {"needs_action": KEY}}),
+ {"sources": ["Tavily"], "reason_key": "reason.service_key_invalid", "to": "DeepSeek"},
+ ("Tavily has an invalid key; switched to DeepSeek", "Tavily 密钥无效,已改用 DeepSeek"),
+ id="one Source, with its reason",
+ ),
+ pytest.param(
+ (_skip(TAVILY, "blocked", needs_action=KEY), _tried(EXA, error_code="service_unavailable", usd=0.0),
+ _tried(DEEPSEEK, "completed", usd=0.0)), LABELS, _now({TAVILY: {"needs_action": KEY}}),
+ {"sources": ["Tavily", "Exa"], "reason_key": "reason.failed", "to": "DeepSeek"},
+ ("Tavily, Exa failed; switched to DeepSeek", "Tavily、Exa 失败,已改用 DeepSeek"),
+ id="several Sources failed",
+ ),
+ pytest.param(
+ (_tried(TAVILY, error_code="service_key_invalid", usd=0.0), _tried(DEEPSEEK, "completed", usd=0.0)),
+ {TAVILY: "My Tavily"}, _now({DEEPSEEK: None}),
+ {"sources": ["My Tavily"], "reason_key": "reason.superseded", "to": "DeepSeek"},
+ ("My Tavily failed on this request; a later action has since updated its state; switched to DeepSeek",
+ "My Tavily 这次请求失败,状态已由之后的操作更新,已改用 DeepSeek"),
+ id="a Source renamed and repaired since, and one removed",
+ ),
+ pytest.param(
+ (_skip(TAVILY, "cooling", retry_at="2026-10-21T04:30:00Z"), _skip(EXA, "query_too_long"),
+ _skip(CLAUDE, "unavailable", kind="model"), _tried(DEEPSEEK, "completed", usd=0.0)), LABELS, HEALTHY,
+ None, None, id="cooling, a long query and a Source gone since are no failure",
+ ),
+ ],
+)
+def test_a_completed_search_names_the_sources_it_moved_past(attempts, names, state, switch, notes):
+ """§4.3, §6.5: the switch note names the failed Sources and the blocked and disabled skips before the one that
+ answered, each Source by its current name, else the name it was recorded with."""
+
+ activity = _chain(attempts, execution=_service_ran(DEEPSEEK, "deepseek"), names=names, state=state)
+ assert activity.to_payload().get("switch") == switch
+ for lang, note in zip(("en", "zh"), notes or (None, None)):
+ line = hosted_line(activity, lang)
+ assert (f" · {note} · " in line) if note else (" · DeepSeek · " in line)
+
+
+ATTEMPT_COPY = (
+ "reason.failed",
+ "reason.superseded",
+ *(f"reason.{code}" for code in HOSTED_ERROR_CODES if code.startswith("service_")),
+ *(f"skip.{reason}" for reason in HOSTED_SKIP_REASONS),
+ *(f"repair.{repair}" for repair in (
+ "key", "reauthorize", "balance", "balanceReenable", "limit", "limitReenable", "tavilyLimit", "plan",
+ "account", "error", "disabled",
+ )),
+ "listSeparator",
+ "itemSeparator",
+ "switch",
+)
+
+
[email protected]("key", ATTEMPT_COPY)
+def test_every_word_a_search_chain_is_shown_with_has_copy_on_every_surface(key):
+ """§6.5: each reason and repair the projection can choose reads in both languages on the IM line and the Web
+ card, which name it by the same key under their hosted-tool copy."""
+
+ for lang in ("en", "zh"):
+ im = f"hostedTools.{key}"
+ assert i18n_t(im, lang) != im, f"vibe/i18n/{lang}.json has no {im}"
+ node = json.loads((UI_BUNDLES / f"{lang}.json").read_text(encoding="utf-8"))["chat"]["agentActivity"]["hosted"]
+ for part in key.split("."):
+ node = node.get(part, {}) if isinstance(node, dict) else {}
+ assert isinstance(node, str) and node, f"ui/src/i18n/{lang}.json has no chat.agentActivity.hosted.{key}"
diff --git a/tests/test_model_hub_api.py b/tests/test_model_hub_api.py
index 73519e677..26c55afec 100644
--- a/tests/test_model_hub_api.py
+++ b/tests/test_model_hub_api.py
@@ -1062,7 +1062,7 @@ def test_runtime_start_is_explicit_and_returns_v4_status(tmp_path):
assert adapter.start_calls == 1
assert store.config.enabled is True
assert runtime["enabled"] is True
- assert runtime["contract_version"] == 18
+ assert runtime["contract_version"] == 19
assert runtime["status"]["health"] == "ok"
_assert_valid("runtime-dependency.schema.json", runtime)
@@ -1369,7 +1369,7 @@ def test_runtime_start_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 18, "status": {"health": "ok"}}
+ return {"contract_version": 19, "status": {"health": "ok"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1386,7 +1386,7 @@ def test_runtime_stop_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 18, "status": {"health": "not_started"}}
+ return {"contract_version": 19, "status": {"health": "not_started"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1403,7 +1403,7 @@ def test_runtime_install_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 18, "status": {"health": "installing"}}
+ return {"contract_version": 19, "status": {"health": "installing"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1421,7 +1421,7 @@ def test_runtime_dependency_ensure_crosses_the_controller_rpc_boundary(monkeypat
def rpc(operation, payload=None):
calls.append((operation, payload))
return {
- "contract_version": 18,
+ "contract_version": 19,
"changed": True,
"status": {"health": "not_started", "verified": True},
}
@@ -4873,7 +4873,7 @@ def test_agent_models_route_returns_only_picker_catalog_fields(monkeypatch):
assert response.status_code == 200
assert response.get_json() == {
"ok": True,
- "contract_version": 18,
+ "contract_version": 19,
"agent": {
"backend": "codex",
"mode": "hub",
@@ -10150,7 +10150,7 @@ def test_runtime_start_route_requires_csrf_before_starting_engine(monkeypatch, t
assert accepted.status_code == 200
runtime = accepted.get_json()["runtime"]
assert adapter.start_calls == 1
- assert runtime["contract_version"] == 18
+ assert runtime["contract_version"] == 19
_assert_valid("runtime-dependency.schema.json", runtime)
diff --git a/tests/test_model_hub_capability_evidence.py b/tests/test_model_hub_capability_evidence.py
index 6fef3b4cb..bc7b143c0 100644
--- a/tests/test_model_hub_capability_evidence.py
+++ b/tests/test_model_hub_capability_evidence.py
@@ -351,13 +351,18 @@ def test_a_write_reads_the_sources_as_they_are_when_it_runs(tmp_path):
}
-def test_persisted_records_match_the_schema_and_rc_era_ones_are_pruned(tmp_path):
- """MH-HOSTED-003: an rc build's probe records (version 1) do not load; nothing migrates them."""
[email protected]("mode", ["native", "executor", "direct", "service"])
+def test_persisted_records_match_the_schema_and_rc_era_ones_are_pruned(tmp_path, mode):
+ """MH-HOSTED-003: every execution mode survives a restart; rc probe records still do not load.
+
+ S2a adds service-mode reader acceptance without writing it from any live path.
+ """
path = tmp_path / "model_hub_capability_evidence.json"
store = CapabilityEvidenceStore(path)
source = _source()
store.write_refusal(_refusal(source, ULTRA), live=lambda: [source], wire_for=WIRE_FOR)
- store.note_success(_success(source, CALL), live=lambda: [source], now=NOW)
+ store.note_success(_success(source, CALL, mode=mode), live=lambda: [source], now=NOW)
+ assert CapabilityEvidenceStore(path).get(source.id, "grok-4.6", CALL, "verified").mode == mode
schema = json.loads((CONTRACTS / "capability-evidence.schema.json").read_text())
validator = Draft7Validator(schema, registry=Registry().with_resources([(schema["$id"], Resource.from_contents(schema))]))
written = json.loads(path.read_text())
diff --git a/tests/test_model_hub_config.py b/tests/test_model_hub_config.py
index 190164fea..028a2dd09 100644
--- a/tests/test_model_hub_config.py
+++ b/tests/test_model_hub_config.py
@@ -97,7 +97,7 @@ def test_auto_detect_asks_for_responses_before_chat():
def test_unsaved_observation_schema_closes_all_terminal_shapes():
schema = _schema("observation-result.schema.json")
- assert schema["properties"]["contract_version"]["const"] == 18
+ assert schema["properties"]["contract_version"]["const"] == 19
assert tuple(schema["properties"]["outcome"]["enum"]) == tuple(
member.value for member in ObservationOutcome
)
@@ -121,7 +121,7 @@ def test_observation_terminal_authority_and_schema_accept_the_same_products():
def payload(observation: SourceObservation) -> dict:
return {
- "contract_version": 18,
+ "contract_version": 19,
"outcome": observation.outcome.value,
"reachable": observation.reachable,
"authenticated": (
@@ -737,7 +737,7 @@ def test_guard_refusal_error_requires_its_corresponding_nonempty_plan_array():
route_refusal = {
"ok": False,
- "contract_version": 18,
+ "contract_version": 19,
"error": "source_in_route_chain",
"detail": "modelHub.errors.source_in_route_chain",
"would_remove_hops": [hop],
@@ -753,7 +753,7 @@ def test_guard_refusal_error_requires_its_corresponding_nonempty_plan_array():
}
candidate_refusal = {
"ok": False,
- "contract_version": 18,
+ "contract_version": 19,
"error": "candidate_suppliers_changed",
"detail": "modelHub.errors.candidate_suppliers_changed",
"changed": {
@@ -837,7 +837,7 @@ def test_v8_mirror_registry_is_executable_and_complete():
registry = json.loads((CONTRACTS / "mirror-registry.json").read_text(encoding="utf-8"))
schemas = _mirror_schemas(registry)
- assert registry["contract_version"] == 18
+ assert registry["contract_version"] == 19
ids = [entry["id"] for entry in registry["entries"]]
assert ids
assert len(ids) == len(set(ids))
@@ -974,8 +974,8 @@ def test_model_hub_authority_closure_anchors_the_persisted_version_floor(monkeyp
"kind": "contract_version_schema_drift",
"domain": "V1",
"file": "docs/plans/model-hub-contracts/turn-provenance.schema.json",
- "values": [6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
- "expected": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
+ "values": [6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
+ "expected": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
} in result["findings"]
@@ -1286,7 +1286,7 @@ def test_v5_shape_amendments_reject_the_false_states_they_replace():
with pytest.raises(ValidationError):
chain_validator.validate(interrupted)
exact_hop = {
- "contract_version": 18,
+ "contract_version": 19,
"backend": "claude",
"model_id": "claude-opus-4-6",
"manual_override": None,
diff --git a/tests/test_model_hub_l3.py b/tests/test_model_hub_l3.py
index 0d058b0cc..fa44512f8 100644
--- a/tests/test_model_hub_l3.py
+++ b/tests/test_model_hub_l3.py
@@ -5580,7 +5580,7 @@ def test_backend_failure_keeps_the_gateway_terminal_error_no_later_request_super
def test_released_backend_rejection_records_read_unchanged(tmp_path: Path) -> None:
"""Records the earlier bridge wrote stay as written: no reason or phase is re-derived on read."""
released = {
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": "turn_released_rejection",
"ts": NOW.isoformat(),
"agent": "vibey",
@@ -7056,7 +7056,7 @@ def test_source_observation_reduces_the_order_at_the_first_authenticated_proof(
_assert_valid(
"observation-result.schema.json",
{
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "adapter_error",
"reachable": True,
"authenticated": "unknown",
@@ -9590,7 +9590,7 @@ def test_native_chain_visibility_and_probe_readiness(tmp_path: Path) -> None:
probe = asyncio.run(service.probe_agent("codex", "shared-model"))
assert probe == {
- "contract_version": 18,
+ "contract_version": 19,
"backend": "codex",
"channel": "native_cli",
"reachable": True,
diff --git a/tests/test_model_hub_provenance.py b/tests/test_model_hub_provenance.py
index e15421fc0..a8bfd5369 100644
--- a/tests/test_model_hub_provenance.py
+++ b/tests/test_model_hub_provenance.py
@@ -261,7 +261,7 @@ def test_live_recovery_snapshots_never_revive_invalid_or_terminal_owners(tmp_pat
def _record(turn_id, *, backend="claude", model=MODEL, outcome="failed_terminal"):
identity = {"source_id": "src_deleted01", "configured_model_id": "unknown-model", "channel": "hub"}
return {
- "contract_version": 18,
+ "contract_version": 19,
"turn_id": turn_id,
"ts": "2026-09-06T00:00:00Z",
"agent": backend,
@@ -461,6 +461,6 @@ def test_model_history_client_rpc_http_share_nullable_read_only_result(monkeypat
f"/api/models/agents/claude/provenance?model={MODEL}", headers=csrf_headers(client, origin), base_url=origin
)
assert response.status_code == 200
- assert response.get_json() == {"ok": True, "contract_version": 18, "provenance": record}
+ assert response.get_json() == {"ok": True, "contract_version": 19, "provenance": record}
assert store.config.to_payload() == before
assert adapter.synced == []
diff --git a/tests/test_model_hub_resolution.py b/tests/test_model_hub_resolution.py
index a13285dfb..37b9bc212 100644
--- a/tests/test_model_hub_resolution.py
+++ b/tests/test_model_hub_resolution.py
@@ -1808,7 +1808,7 @@ def test_service_accepts_authoritative_reachable_adapter_error(tmp_path):
)
assert result["observation"] == {
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "adapter_error",
"reachable": True,
"authenticated": "unknown",
@@ -1839,7 +1839,7 @@ def test_unknown_adapter_error_does_not_claim_connection(tmp_path):
assert exc.value.code == "discovery_failed"
assert exc.value.detail == "modelHub.errors.adapter_error"
assert exc.value.data["observation"] == {
- "contract_version": 18,
+ "contract_version": 19,
"outcome": "adapter_error",
"reachable": None,
"authenticated": "unknown",
diff --git a/tests/test_model_hub_runtime.py b/tests/test_model_hub_runtime.py
index f62c3332e..d7ebdcf2d 100644
--- a/tests/test_model_hub_runtime.py
+++ b/tests/test_model_hub_runtime.py
@@ -1367,7 +1367,7 @@ def test_manifest_resolution_drives_admission_persistence_and_schema(
installer=manager,
state_store=EngineStateStore(tmp_path / "state"),
)
- projected = {"contract_version": 18, **supervisor.status()}
+ projected = {"contract_version": 19, **supervisor.status()}
schema = json.loads(
Path("docs/plans/model-hub-contracts/runtime-dependency.schema.json").read_text(
encoding="utf-8"
diff --git a/tests/test_model_hub_service_usage.py b/tests/test_model_hub_service_usage.py
new file mode 100644
index 000000000..ae5dde6b3
--- /dev/null
+++ b/tests/test_model_hub_service_usage.py
@@ -0,0 +1,595 @@
+"""Search-service usage in the Model Hub ledger (`web-search-services.md` §4.3).
+
+A sent search request reaches no model, so the ledger keeps it in its own row per
+Source and catalog `service_id`, through the same daily and hourly lifecycle as
+model calls. These tests hold the service half of that contract at the ledger and
+writer boundary: its counts and their repaired relations, its separation from
+model usage, its valuation at the current catalog, and the summary's presence
+rules. The model half is held by `test_model_hub_usage.py`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from core.handlers.model_hub.pricing import PriceTable
+from core.handlers.model_hub.stream_wire import ProtocolUsageReport
+from core.handlers.model_hub.usage import (
+ BoundedUsageLedger,
+ ServiceCatalogEntry,
+ ServiceUsageCall,
+ SourceIdentity,
+ UsageCall,
+ UsageWriter,
+ local_usage_day,
+)
+
+NOW = datetime(2026, 10, 20, 12, 0, tzinfo=timezone.utc)
+CATALOG = (
+ ServiceCatalogEntry(service_id="deepseek/search", label="DeepSeek", usd_per_1k=0.75, price_date="2026-10-19"),
+ ServiceCatalogEntry(service_id="exa/search", label="Exa", usd_per_1k=7.0, price_date="2026-10-18"),
+ ServiceCatalogEntry(service_id="tavily/search", label="Tavily", usd_per_1k=8.0, price_date="2026-10-19"),
+)
+# deepseek-chat: $1 per million input tokens, $2 per million output tokens.
+PRICES = PriceTable(
+ catalog={},
+ vendor_map={},
+ overrides={"models": {"deepseek-chat": {"input": 1, "output": 2}}},
+ price_table_date="2026-10-20",
+)
+MODEL_COUNTERS = {
+ "requests",
+ "token_reports",
+ "input_tokens",
+ "cached_input_tokens",
+ "output_tokens",
+ "cache_write_input_tokens",
+ "cache_write_1h_input_tokens",
+ "cache_write_uncaptured_reports",
+}
+
+
+def _ledger(tmp_path: Path, **kwargs) -> BoundedUsageLedger:
+ return BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW, **kwargs)
+
+
+def _service(summary: dict, service_id: str) -> dict:
+ (entry,) = [entry for entry in summary["services"] if entry["service_id"] == service_id]
+ return entry
+
+
+def _assert_valid(payload: dict) -> None:
+ from jsonschema import Draft7Validator, FormatChecker
+
+ schema = json.loads(
+ (Path(__file__).parents[1] / "docs" / "plans" / "model-hub-contracts" / "usage-summary.schema.json").read_text(
+ encoding="utf-8"
+ )
+ )
+ errors = [error.message for error in Draft7Validator(schema, format_checker=FormatChecker()).iter_errors(payload)]
+ assert not errors, errors
+
+
+def test_service_requests_are_their_own_rows_beside_model_usage(tmp_path):
+ """A service request never counts as a model call, a Source row or quota value; its list price joins the totals."""
+
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ UsageCall(
+ source_id="src_deepseek",
+ model_id="deepseek-chat",
+ usage=ProtocolUsageReport.of(input_tokens=1_000_000, cached_input_tokens=0, output_tokens=500_000),
+ at=NOW,
+ ),
+ ServiceUsageCall(source_id="src_deepseek", service_id="deepseek/search", at=NOW, billable_requests=1),
+ # An empty DeepSeek answer: sent, not billed.
+ ServiceUsageCall(source_id="src_deepseek", service_id="deepseek/search", at=NOW),
+ # An unreadable DeepSeek 200: sent, billing unknown.
+ ServiceUsageCall(source_id="src_deepseek", service_id="deepseek/search", at=NOW, uncertain_requests=1),
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW,
+ billable_requests=1, reported_requests=1, reported_usd=0.0065,
+ ),
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW,
+ billable_requests=1, reported_requests=1, reported_usd=0.0075,
+ ),
+ ])
+ identities = [
+ SourceIdentity("src_deepseek", "DeepSeek key", ["deepseek-chat"]),
+ SourceIdentity("src_exa", "Exa key"),
+ ]
+
+ # Read back after a restart: the reported figures are the ledger's, not memory's.
+ reopened = BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW)
+ summary = reopened.summary(days=7, now=NOW, identities=identities, prices=PRICES, service_catalog=CATALOG)
+
+ assert summary["totals"]["requests"] == 1
+ # A tool-only Source is no Source row; a DeepSeek Source keeps only its model usage there.
+ assert [source["source_id"] for source in summary["sources"]] == ["src_deepseek"]
+ assert summary["sources"][0]["requests"] == 1
+ assert summary["sources"][0]["api_cost_usd"] == pytest.approx(2.0)
+ metered_at = NOW.isoformat()
+ assert summary["services"] == [
+ {
+ "source_id": "src_deepseek",
+ "service_id": "deepseek/search",
+ "label": "DeepSeek key",
+ "service_label": "DeepSeek",
+ "requests": 3,
+ "billable_requests": 1,
+ "uncertain_requests": 1,
+ "reported_requests": 0,
+ "last_metered_at": metered_at,
+ "reported_usd": 0.0,
+ "api_cost_usd": 0.00075,
+ "api_cost_lower_bound": True,
+ "priced": True,
+ },
+ {
+ "source_id": "src_exa",
+ "service_id": "exa/search",
+ "label": "Exa key",
+ "service_label": "Exa",
+ "requests": 2,
+ "billable_requests": 2,
+ "uncertain_requests": 0,
+ "reported_requests": 2,
+ "last_metered_at": metered_at,
+ "reported_usd": 0.014,
+ # The list valuation, never the reported figure.
+ "api_cost_usd": 0.014,
+ "api_cost_lower_bound": False,
+ "priced": True,
+ },
+ ]
+ totals = summary["totals"]
+ assert totals["api_cost_usd"] == pytest.approx(2.0 + 0.00075 + 0.014)
+ assert totals["service_reported_usd"] == 0.014
+ assert totals["excluded_service_requests"] == 0
+ assert totals["api_cost_lower_bound"] is True
+ assert sum(day["api_cost_usd"] for day in summary["days"]) == pytest.approx(totals["api_cost_usd"])
+ assert summary["pricing"] == {
+ "currency": "USD",
+ "price_table_date": "2026-10-20",
+ "service_price_date": "2026-10-18",
+ }
+ # A plan's quota covers model calls; search requests on the same Source are not one.
+ costs = reopened.daily_costs(days=31, now=NOW, identities=identities[:1], prices=PRICES)
+ (day_cost,) = costs["src_deepseek"].values()
+ assert day_cost.api_cost_usd == pytest.approx(2.0)
+ assert day_cost.api_cost_lower_bound is False
+
+
+def test_service_rows_reach_daily_and_hourly_buckets_in_their_own_shape(tmp_path):
+ """Buckets carry `kind: "service"` rows after the model rows, and the 24-hour view keeps only recent hours."""
+
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ UsageCall(source_id="src_deepseek", model_id="deepseek-chat", usage=None, at=NOW - timedelta(hours=1)),
+ ServiceUsageCall(source_id="src_tavily", service_id="tavily/search", at=NOW - timedelta(hours=1), billable_requests=1),
+ ServiceUsageCall(source_id="src_tavily", service_id="tavily/search", at=NOW - timedelta(hours=1), billable_requests=1),
+ ServiceUsageCall(source_id="src_tavily", service_id="tavily/search", at=NOW - timedelta(hours=30), billable_requests=1),
+ ])
+ identities = [SourceIdentity("src_deepseek", "DeepSeek", ["deepseek-chat"]), SourceIdentity("src_tavily", "Tavily")]
+
+ hourly = ledger.report(window="24h", now=NOW, identities=identities, prices=PRICES, service_catalog=CATALOG)
+
+ assert all(bucket["history_complete"] for bucket in hourly["buckets"])
+ (rows,) = [bucket["rows"] for bucket in hourly["buckets"] if bucket["rows"]]
+ assert [row.get("kind") for row in rows] == [None, "service"]
+ assert rows[0]["model_id"] == "deepseek-chat"
+ assert rows[1] == {
+ "kind": "service",
+ "source_id": "src_tavily",
+ "service_id": "tavily/search",
+ "requests": 2,
+ "billable_requests": 2,
+ "uncertain_requests": 0,
+ "reported_requests": 0,
+ "reported_usd": 0.0,
+ "api_cost_usd": 0.016,
+ "api_cost_lower_bound": False,
+ }
+ assert _service(hourly, "tavily/search")["requests"] == 2
+ assert hourly["totals"]["requests"] == 1
+
+ daily = ledger.report(window="7d", now=NOW, identities=identities, prices=PRICES, service_catalog=CATALOG)
+ service_rows = [row for bucket in daily["buckets"] for row in bucket["rows"] if row.get("kind") == "service"]
+ assert sum(row["requests"] for row in service_rows) == 3
+ assert _service(daily, "tavily/search")["api_cost_usd"] == 0.024
+ assert daily["totals"]["api_cost_usd"] == pytest.approx(0.024)
+
+
+def test_without_a_price_table_service_usage_carries_counts_only(tmp_path):
+ """Pricing presence is unchanged: no model price table, no service cost field anywhere, counts still exact."""
+
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW,
+ billable_requests=1, reported_requests=1, reported_usd=0.007,
+ ),
+ ])
+ identities = [SourceIdentity("src_exa", "Exa")]
+
+ summary = ledger.summary(days=7, now=NOW, identities=identities, service_catalog=CATALOG)
+ report = ledger.report(window="7d", now=NOW, identities=identities, service_catalog=CATALOG)
+
+ assert "pricing" not in summary
+ assert summary["services"] == [
+ {
+ "source_id": "src_exa",
+ "service_id": "exa/search",
+ "label": "Exa",
+ "service_label": "Exa",
+ "requests": 1,
+ "billable_requests": 1,
+ "uncertain_requests": 0,
+ "reported_requests": 1,
+ "last_metered_at": NOW.isoformat(),
+ }
+ ]
+ assert set(summary["totals"]) == MODEL_COUNTERS
+ assert all(set(day) == {"day", *MODEL_COUNTERS} for day in summary["days"])
+ (service_row,) = [row for bucket in report["buckets"] for row in bucket["rows"]]
+ assert set(service_row) == {
+ "kind", "source_id", "service_id", "requests", "billable_requests", "uncertain_requests", "reported_requests",
+ }
+
+
+def _persisted_service_row(**counts) -> dict:
+ return {
+ "day": local_usage_day(NOW).isoformat(),
+ "source_id": "src_exa",
+ "service_id": "exa/search",
+ "last_metered_at": NOW.isoformat(),
+ **counts,
+ }
+
+
+# (stored fields) -> (billable, uncertain, reported_requests, reported_usd, lower_bound); requests is always kept.
+REPAIRS = {
+ "consistent": (
+ {"requests": 3, "billable_requests": 2, "uncertain_requests": 0, "reported_requests": 1, "reported_usd": 0.5},
+ (2, 0, 1, 0.5, False),
+ ),
+ "a row without the additive fields loads as zero": ({"requests": 2}, (0, 0, 0, 0.0, False)),
+ "billing unknown is always a floor": (
+ {"requests": 3, "billable_requests": 1, "uncertain_requests": 1, "reported_requests": 0, "reported_usd": 0},
+ (1, 1, 0, 0.0, True),
+ ),
+ "a stored floor stays a floor": (
+ {"requests": 1, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 0, "reported_usd": 0,
+ "lower_bound": True},
+ (1, 0, 0, 0.0, True),
+ ),
+ "billable past requests drops the reports it no longer covers": (
+ {"requests": 2, "billable_requests": 5, "uncertain_requests": 0, "reported_requests": 3, "reported_usd": 0.3},
+ (2, 0, 0, 0.0, True),
+ ),
+ "reducing billable drops every dependent report even inside the new bound": (
+ {"requests": 2, "billable_requests": 3, "uncertain_requests": 0, "reported_requests": 1, "reported_usd": 0.2},
+ (2, 0, 0, 0.0, True),
+ ),
+ "invalid count marks a floor": (
+ {"requests": 2, "billable_requests": -1, "uncertain_requests": 0, "reported_requests": 0, "reported_usd": 0},
+ (0, 0, 0, 0.0, True),
+ ),
+ "uncertain past what billing leaves": (
+ {"requests": 3, "billable_requests": 2, "uncertain_requests": 4, "reported_requests": 0, "reported_usd": 0},
+ (2, 1, 0, 0.0, True),
+ ),
+ "reported past billable": (
+ {"requests": 3, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 2, "reported_usd": 0.2},
+ (1, 0, 0, 0.0, True),
+ ),
+ "orphaned reported dollars": (
+ {"requests": 1, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 0, "reported_usd": 0.4},
+ (1, 0, 0, 0.0, True),
+ ),
+ "reported past a dollar a request": (
+ {"requests": 2, "billable_requests": 2, "uncertain_requests": 0, "reported_requests": 1, "reported_usd": 1.5},
+ (2, 0, 0, 0.0, True),
+ ),
+ "a non-finite reported amount": (
+ {"requests": 1, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 1,
+ "reported_usd": float("nan")},
+ (1, 0, 0, 0.0, True),
+ ),
+ "a negative reported amount": (
+ {"requests": 1, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 1, "reported_usd": -0.1},
+ (1, 0, 0, 0.0, True),
+ ),
+}
+
+
[email protected]("stored, expected", list(REPAIRS.values()), ids=list(REPAIRS))
[email protected]("door", ["read", "write"])
+def test_a_service_row_keeps_its_relations_on_read_and_on_write(tmp_path, stored, expected, door):
+ """An impossible counter set is published, and rewritten, as the smaller true statement, marked a floor."""
+
+ path = tmp_path / "usage.json"
+ # `json.dumps` spells a non-finite float as `NaN`, which a hand-edited file can hold.
+ ledger = BoundedUsageLedger(path, now=lambda: NOW)
+ if door == "read" or stored.get("lower_bound"):
+ # lower_bound is a persisted fact, not a caller-supplied usage quantity.
+ path.write_text(json.dumps([_persisted_service_row(**stored)]), encoding="utf-8")
+ else:
+ ledger.record_many([ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=NOW, **stored)])
+ billable, uncertain, reported_requests, reported_usd, lower_bound = expected
+
+ service = _service(
+ ledger.summary(days=7, now=NOW, identities=[SourceIdentity("src_exa", "Exa")], prices=PRICES,
+ service_catalog=CATALOG),
+ "exa/search",
+ )
+ assert (
+ service["requests"], service["billable_requests"], service["uncertain_requests"],
+ service["reported_requests"], service["reported_usd"], service["api_cost_lower_bound"],
+ ) == (stored["requests"], billable, uncertain, reported_requests, reported_usd, lower_bound)
+ assert service["api_cost_usd"] == pytest.approx(billable * 7.0 / 1000)
+
+ # Any write rewrites the file; what it keeps is the repaired row, never the stored one.
+ ledger.record_many([UsageCall(source_id="src_other", model_id="m", usage=None, at=NOW)])
+ (persisted,) = [row for row in json.loads(path.read_text(encoding="utf-8")) if "service_id" in row]
+ assert "model_id" not in persisted
+ assert (
+ persisted["requests"], persisted["billable_requests"], persisted["uncertain_requests"],
+ persisted["reported_requests"], persisted["reported_usd"], persisted["lower_bound"],
+ ) == (stored["requests"], billable, uncertain, reported_requests, reported_usd, lower_bound)
+
+
+def test_a_repaired_row_leaves_its_hours_partial(tmp_path):
+ """Counts reduced on read no longer match the hours written beside them, so the 24-hour view says it is partial."""
+
+ path = tmp_path / "usage.json"
+ hour = (NOW - timedelta(hours=1)).replace(minute=0)
+ slice_counts = {"requests": 1, "billable_requests": 1, "uncertain_requests": 0, "reported_requests": 0,
+ "reported_usd": 0.0}
+ row = _persisted_service_row(
+ requests=1, billable_requests=2, uncertain_requests=0, reported_requests=0, reported_usd=0.0,
+ last_metered_at=hour.isoformat(),
+ hours=[{"key": hour.isoformat(timespec="seconds"), **slice_counts, "last_metered_at": hour.isoformat()}],
+ hourly_expired_totals={**slice_counts, "requests": 0, "billable_requests": 0},
+ hourly_history_complete=True,
+ )
+ path.write_text(json.dumps([row]), encoding="utf-8")
+
+ report = BoundedUsageLedger(path, now=lambda: NOW).report(
+ window="24h", now=NOW, identities=[SourceIdentity("src_exa", "Exa")], prices=PRICES, service_catalog=CATALOG
+ )
+
+ assert not all(bucket["history_complete"] for bucket in report["buckets"])
+ assert report["totals"]["api_cost_lower_bound"] is True
+
+
+
+
+def test_an_uncertain_service_hour_does_not_floor_an_exact_sibling(tmp_path):
+ """Hourly cost floors follow the slice's uncertainty, not a different slice's daily witness."""
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW - timedelta(hours=2), uncertain_requests=1,
+ ),
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW - timedelta(hours=1), billable_requests=1,
+ ),
+ ])
+
+ report = ledger.report(window="24h", now=NOW, prices=PRICES, service_catalog=CATALOG)
+ service_rows = [row for bucket in report["buckets"] for row in bucket["rows"] if row.get("kind") == "service"]
+ uncertain = next(row for row in service_rows if row["uncertain_requests"] == 1)
+ exact = next(row for row in service_rows if row["billable_requests"] == 1)
+ assert uncertain["api_cost_lower_bound"] is True
+ assert exact["api_cost_lower_bound"] is False
+ assert report["totals"]["api_cost_lower_bound"] is True
+
+
[email protected]("billable", [0, 1])
+def test_a_removed_catalog_row_is_unpriced_even_without_billable_requests(tmp_path, billable):
+ """§4.3 marks a removed service unpriced and lower-bound, independent of its historical billable count."""
+ ledger = _ledger(tmp_path)
+ ledger.record_many([ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=NOW,
+ billable_requests=billable)])
+ summary = ledger.summary(now=NOW, prices=PRICES)
+ service = _service(summary, "exa/search")
+ assert (service["priced"], service["api_cost_lower_bound"]) == (False, True)
+ assert summary["totals"]["excluded_service_requests"] == billable
+ _assert_valid(summary)
+
+
+def test_the_current_catalog_values_service_rows_and_a_dropped_one_stays_counted(tmp_path):
+ """Usage values stored requests at today's catalog; a removed Source or catalog row keeps counts and reported cost."""
+
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ ServiceUsageCall(
+ source_id="src_exa", service_id="exa/search", at=NOW,
+ billable_requests=1, reported_requests=1, reported_usd=0.007,
+ ),
+ ServiceUsageCall(source_id="src_gone", service_id="tavily/search", at=NOW, billable_requests=1),
+ ServiceUsageCall(source_id="src_gone", service_id="tavily/search", at=NOW, billable_requests=1),
+ ])
+ identities = [SourceIdentity("src_exa", "Exa")]
+ tavily_only = [ServiceCatalogEntry(service_id="tavily/search", label="Tavily", usd_per_1k=8.0, price_date="2026-10-19")]
+ repriced = [ServiceCatalogEntry(service_id="tavily/search", label="Tavily", usd_per_1k=5.0, price_date="2026-11-01")]
+
+ summary = ledger.summary(days=7, now=NOW, identities=identities, prices=PRICES, service_catalog=tavily_only)
+
+ exa = _service(summary, "exa/search")
+ assert (exa["priced"], exa["service_label"], exa["api_cost_usd"], exa["api_cost_lower_bound"]) == (
+ False, None, 0.0, True,
+ )
+ assert exa["reported_usd"] == 0.007
+ tavily = _service(summary, "tavily/search")
+ # The Source was removed: no label, still its own row with its own counts.
+ assert (tavily["label"], tavily["requests"], tavily["api_cost_usd"], tavily["priced"]) == (None, 2, 0.016, True)
+ totals = summary["totals"]
+ assert (totals["api_cost_usd"], totals["excluded_service_requests"], totals["service_reported_usd"]) == (
+ 0.016, 1, 0.007,
+ )
+ assert totals["api_cost_lower_bound"] is True
+ assert summary["pricing"]["service_price_date"] == "2026-10-19"
+
+ later = ledger.summary(days=7, now=NOW, identities=identities, prices=PRICES, service_catalog=repriced)
+ assert _service(later, "tavily/search")["api_cost_usd"] == 0.01
+ assert later["pricing"]["service_price_date"] == "2026-11-01"
+ # A summary that values no service has no service price to date.
+ assert "service_price_date" not in ledger.summary(days=7, now=NOW, identities=identities, prices=PRICES)["pricing"]
+
+
+def test_hourly_history_reconciles_although_reported_sums_depend_on_order(tmp_path):
+ """Counts reconcile exactly; a reported float sum is bounded, never compared, so its order cannot mark hours partial."""
+
+ early, late = NOW - timedelta(hours=3), NOW - timedelta(hours=2)
+ ledger = _ledger(tmp_path)
+ # The day adds 0.001 + 0.001 + 0.008; its hours add (0.001 + 0.008) + 0.001, a different double.
+ ledger.record_many([
+ ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=early, billable_requests=1,
+ reported_requests=1, reported_usd=0.001),
+ ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=late, billable_requests=1,
+ reported_requests=1, reported_usd=0.001),
+ ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=early, billable_requests=1,
+ reported_requests=1, reported_usd=0.008),
+ ])
+
+ report = ledger.report(
+ window="24h", now=NOW, identities=[SourceIdentity("src_exa", "Exa")], prices=PRICES, service_catalog=CATALOG
+ )
+
+ assert all(bucket["history_complete"] for bucket in report["buckets"])
+ assert report["totals"]["api_cost_lower_bound"] is False
+ assert _service(report, "exa/search")["reported_usd"] == 0.01
+
+
+def test_the_writer_folds_service_requests_exactly_and_apart_from_a_same_named_model(tmp_path):
+ """Queued requests fold into the row their separate writes would reach; a model ID equal to a service id stays a model."""
+
+ ledger = _ledger(tmp_path)
+ writer = UsageWriter(ledger)
+
+ async def meter() -> None:
+ writer.record_service(source_id="src_exa", service_id="exa/search", billable=True, reported_usd=0.007, at=NOW)
+ writer.record_service(source_id="src_exa", service_id="exa/search", billable=True, at=NOW)
+ writer.record_service(source_id="src_exa", service_id="exa/search", billable=False, uncertain=True, at=NOW)
+ writer.record_service(source_id="src_exa", service_id="exa/search", billable=False, at=NOW)
+ writer.record(source_id="src_exa", model_id="exa/search", usage=None, at=NOW)
+ assert writer.unpersisted == 5
+ assert await writer.drain(timeout=5) == 0
+
+ asyncio.run(meter())
+ summary = ledger.summary(days=7, now=NOW, identities=[SourceIdentity("src_exa", "Exa", ["exa/search"])],
+ prices=PRICES, service_catalog=CATALOG)
+
+ service = _service(summary, "exa/search")
+ assert (
+ service["requests"], service["billable_requests"], service["uncertain_requests"],
+ service["reported_requests"], service["reported_usd"], service["api_cost_lower_bound"],
+ ) == (4, 2, 1, 1, 0.007, True)
+ assert summary["totals"]["requests"] == 1
+ assert summary["sources"][0]["models"][0]["model_id"] == "exa/search"
+
+
[email protected]("first, expected", [
+ ({"billable": True, "reported_usd": 1.5}, (2, 1, 0.25)),
+ ({"billable": False, "reported_usd": 0.5}, (1, 1, 0.25)),
+ ({"billable": True, "reported_usd": -0.1}, (2, 1, 0.25)),
+ ({"billable": True, "reported_usd": True}, (2, 1, 0.25)),
+ ({"billable": True, "reported_usd": float("nan")}, (2, 1, 0.25)),
+ ({"billable": True, "reported_usd": float("inf")}, (2, 1, 0.25)),
+ ({"billable": True, "uncertain": True}, (2, 1, 0.25)),
+ ({"billable": 1, "reported_usd": 0.5}, (1, 1, 0.25)),
+ ({"billable": 1.5}, (1, 1, 0.25)),
+ ({"billable": "yes"}, (1, 1, 0.25)),
+ ({"billable": None}, (1, 1, 0.25)),
+ ({"billable": True, "uncertain": "x"}, (2, 1, 0.25)),
+])
+def test_writer_repairs_each_request_before_a_fold_can_hide_its_corruption(tmp_path, first, expected):
+ """Queue folding must equal separate writes: valid later calls cannot legitimize an invalid earlier report."""
+ ledger = _ledger(tmp_path)
+ writer = UsageWriter(ledger)
+
+ async def meter():
+ writer.record_service(source_id="src_exa", service_id="exa/search", at=NOW, **first)
+ writer.record_service(source_id="src_exa", service_id="exa/search", at=NOW,
+ billable=True, reported_usd=0.25)
+ assert await writer.drain(timeout=5) == 0
+
+ asyncio.run(meter())
+ service = _service(ledger.summary(now=NOW, prices=PRICES, service_catalog=CATALOG), "exa/search")
+ assert (service["billable_requests"], service["reported_requests"], service["reported_usd"]) == expected
+ assert service["requests"] == 2
+ assert service["api_cost_lower_bound"] is True
+
+
+def test_service_rows_share_the_ledger_retention_and_capacity(tmp_path):
+ """A service row ages out of the window and competes for the row capacity by recency, as a model row does."""
+
+ ledger = _ledger(tmp_path, max_rows=2)
+ ledger.record_many([
+ ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=NOW - timedelta(days=70), billable_requests=1),
+ UsageCall(source_id="src_deepseek", model_id="deepseek-chat", usage=None, at=NOW - timedelta(hours=2)),
+ ServiceUsageCall(source_id="src_tavily", service_id="tavily/search", at=NOW - timedelta(hours=1)),
+ ServiceUsageCall(source_id="src_deepseek", service_id="deepseek/search", at=NOW),
+ ])
+
+ persisted = json.loads((tmp_path / "usage.json").read_text(encoding="utf-8"))
+
+ assert sorted(row.get("service_id") or row["model_id"] for row in persisted) == [
+ "deepseek/search", "tavily/search",
+ ]
+
+
+def test_service_usage_reads_stay_inside_the_usage_summary_contract(tmp_path):
+ """A tool-only Source's usage validates against the closed schema, priced or not, in every read shape."""
+
+ ledger = _ledger(tmp_path)
+ ledger.record_many([
+ ServiceUsageCall(source_id="src_exa", service_id="exa/search", at=NOW - timedelta(hours=1), billable_requests=1,
+ reported_requests=1, reported_usd=0.007),
+ ServiceUsageCall(source_id="src_gone", service_id="retired/search", at=NOW, uncertain_requests=1),
+ ])
+ identities = [SourceIdentity("src_exa", "Exa")]
+
+ for prices in (PRICES, None):
+ _assert_valid(ledger.summary(days=30, now=NOW, identities=identities, prices=prices, service_catalog=CATALOG))
+ for window in ("24h", "7d"):
+ _assert_valid(
+ ledger.report(window=window, now=NOW, identities=identities, prices=prices, service_catalog=CATALOG)
+ )
+
+
+def test_the_usage_read_values_service_rows_at_the_release_catalog(tmp_path, monkeypatch):
+ """The Model Hub usage read labels and prices a service row from the bundled catalog, not from Source config."""
+
+ from tests.scenario_harness.model_hub import (
+ MemoryModelHubStore,
+ ModelHubScenarioAdapter,
+ config_with_sources,
+ service_for,
+ )
+ from vibe.model_hub_runtime.api_key_vendors import api_key_vendor_entry
+
+ monkeypatch.setenv("VIBE_MODEL_HUB_ENABLED", "1")
+ service = service_for(
+ tmp_path, MemoryModelHubStore(config_with_sources([])), ModelHubScenarioAdapter(), now=lambda: NOW
+ )
+ service.price_table = lambda: PRICES
+ service.usage.record_many([
+ ServiceUsageCall(source_id="src_tavily", service_id="tavily/search", at=NOW, billable_requests=1),
+ ])
+ tavily = api_key_vendor_entry("tavily")
+
+ for usage in (service.usage_summary(window="7d"), service.usage_summary(days=7)):
+ (entry,) = usage["services"]
+ assert entry["service_label"] == tavily.label
+ assert entry["priced"] is True
+ assert entry["api_cost_usd"] == pytest.approx(tavily.search["price"]["usd_per_1k"] / 1000)
+ assert usage["pricing"]["service_price_date"] == tavily.search["price"]["as_of"]
diff --git a/tests/test_model_hub_vibey_contract_matrix.py b/tests/test_model_hub_vibey_contract_matrix.py
index 47d447838..c18bad33c 100644
--- a/tests/test_model_hub_vibey_contract_matrix.py
+++ b/tests/test_model_hub_vibey_contract_matrix.py
@@ -48,13 +48,13 @@ def _fixture(kind):
# Start from a valid native response so no Hub latency constraint can
# accidentally reject the Avibe/native pairing for an unrelated cause.
return {
- "contract_version": 18, "backend": "claude", "channel": "native_cli", "reachable": True,
+ "contract_version": 19, "backend": "claude", "channel": "native_cli", "reachable": True,
"source_id": "src_fixture01", "model_id": "fixture-model", "latency_ms": None,
"error": None,
}
if kind == "chain":
return {
- "contract_version": 18, "backend": "vibey", "model_id": "fixture-model",
+ "contract_version": 19, "backend": "vibey", "model_id": "fixture-model",
"manual_override": None, "route_origin": "automatic",
"chain": [{"source_id": "src_fixture01", "model_id": "fixture-model", "channel": "hub",
"health": "healthy", "runnable": True, "reason": None, "retry_at": None}],
@@ -66,7 +66,7 @@ def _fixture(kind):
"proposed_action": "import", "selected": False,
}
return {
- "contract_version": 18, "turn_id": "turn-fixture", "ts": "2026-10-02T07:00:00Z",
+ "contract_version": 19, "turn_id": "turn-fixture", "ts": "2026-10-02T07:00:00Z",
"agent": "vibey", "requested_model_id": "fixture-model", "outcome": kind,
"failed_attempts": [{**identity, "reason": "rate_limited"}] if kind == "exhausted" else [],
"served": identity if kind == "served" else None,
diff --git a/tests/test_vibey_agent.py b/tests/test_vibey_agent.py
index e3439514a..336dc13c5 100644
--- a/tests/test_vibey_agent.py
+++ b/tests/test_vibey_agent.py
@@ -43,6 +43,7 @@ from core.agent_core.messages import (
AssistantMessage,
Citation,
HostedAction,
+ HostedAttempt,
HostedCost,
HostedImage,
HostedNative,
@@ -4993,6 +4994,63 @@ async def test_a_proxied_hosted_result_shows_once_its_result_is_committed(engine
assert harness.controller.im_client.sent[-1:] == ["🔎 X search “from:OpenAI” · via xAI proxy (grok-4.6) · 1 post · $0.11"]
+async def test_a_search_chain_shows_its_sources_as_model_hub_holds_them_now(
+ engine, session, tmp_path, published
+) -> None:
+ """MH-HOSTED-UI-010 (web-search-services.md §4.3): each Source a search chain reached is shown as Model Hub holds
+ it now, read with its health and its search switch: renamed since, it shows its new name; still blocked or
+ turned off, its repair; a failure whose key was replaced since, no repair at all."""
+ from modules.agents.vibey.agent import _Run
+ from tests.test_model_hub_hosted_tools_config import SOURCE
+
+ tavily, deepseek, exa = "src_tavily01", "src_deepseek1", "src_exa00001"
+ revoked = "models.source.needs_action.credential_revoked"
+
+ def source(source_id: str, vendor: str, name: str, protocol: str = "search", **state: Any) -> dict:
+ health = {"status": "standby", "retry_at": None, "detail_key": None, **state}
+ return {**SOURCE, "id": source_id, "vendor": vendor, "display_name": name, "protocol": protocol,
+ "models": [], "credential_ref": f"cred_{source_id}", "state": health}
+
+ hub = ModelHubConfig.from_payload({
+ "sources": [
+ source(tavily, "tavily", "My Tavily", status="needs_action", detail_key=revoked),
+ source(deepseek, "deepseek", "DeepSeek", protocol="openai_chat"),
+ source(exa, "exa", "Exa"),
+ ],
+ "hosted_tools": {"web_search": {"services": {exa: {"enabled": False}}}},
+ })
+ harness = _Harness(engine, tmp_path, "telegram", [[Done(assistant("ok"))]])
+ # A tool result answers a Turn, so the Session has consumed an input first.
+ await harness.agent.handle_message(harness.request("hello"))
+ harness.controller.model_hub_runtime.snapshot = lambda: hub
+ call = ToolCallBlock(id="call_ws1", name="web_search", arguments={"query": "DeepSeek search API pricing"})
+ record = HostedRecord(
+ status="failed",
+ error="every search source is blocked or turned off",
+ error_code="search_sources_blocked",
+ attempts=(
+ HostedAttempt(tavily, "Tavily", "service", "skipped", skipped="blocked", needs_action=revoked),
+ HostedAttempt(deepseek, "DeepSeek", "service", "failed", error_code="service_key_invalid",
+ cost=HostedCost(basis="list", usd=0.0)),
+ HostedAttempt(exa, "Exa", "service", "skipped", skipped="disabled"),
+ ),
+ )
+ result = ToolResultMessage(
+ "call_ws1", "web_search", (text("no results"),), is_error=True, hosted=HostedResult(record)
+ )
+ entry = await harness.agent.store.append_tool_result(SESSION, result, details={})
+ run = _Run(request=harness.request("search it"), session_id=SESSION, turn_id="turn", instance="test")
+ run.tool_calls[call.id] = call
+
+ await harness.agent._on_event(run, ToolFinished("turn", 1, call.id, entry.row_id, True))
+
+ assert harness.controller.im_client.sent[-1:] == [
+ "🔎 Web search “DeepSeek search API pricing” · failed: all search sources are blocked or disabled"
+ " · My Tavily needs a replacement key; DeepSeek failed on this request; a later action has since updated"
+ " its state; Exa needs web search enabled in Models › Tools · $0"
+ ]
+
+
def test_an_image_is_attached_unless_the_reply_already_links_it(tmp_path) -> None:
"""A prose mention of the path is not a delivered file; a relative path names no file to send."""
from modules.agents.vibey.agent import VibeyAgent
diff --git a/ui/e2e/chat-interactions/interactions.spec.ts b/ui/e2e/chat-interactions/interactions.spec.ts
index c9923c587..67105a5cb 100644
--- a/ui/e2e/chat-interactions/interactions.spec.ts
+++ b/ui/e2e/chat-interactions/interactions.spec.ts
@@ -11,7 +11,7 @@ for (const lang of ['en', 'zh'] as const) {
if (url.origin !== 'http://127.0.0.1:5227' || route.request().method() !== 'GET') return route.abort();
if (url.pathname === `/api/models/turns/${TURN}/provenance`) {
return route.fulfill({ json: { provenance: {
- contract_version: 18, turn_id: TURN, agent: 'codex', requested_model_id: 'fixture-model',
+ contract_version: 19, turn_id: TURN, agent: 'codex', requested_model_id: 'fixture-model',
outcome: 'failed_terminal', failed_attempts: [], blockers: [],
terminal_error: { source_id: 'fixture-source', configured_model_id: 'fixture-model', reason: 'engine_down' },
} } });
diff --git a/ui/e2e/model-catalog/gatewayFixture.tsx b/ui/e2e/model-catalog/gatewayFixture.tsx
index 4e8059448..a57e3c6ea 100644
--- a/ui/e2e/model-catalog/gatewayFixture.tsx
+++ b/ui/e2e/model-catalog/gatewayFixture.tsx
@@ -35,13 +35,13 @@ export function GatewayFixture() {
}],
};
const chains = Object.fromEntries(ids.map((model_id, index) => [modelChainKey(backend, model_id), readyRegion<AgentChain>({
- contract_version: 18, backend, model_id, route_origin: origins[index],
+ contract_version: 19, backend, model_id, route_origin: origins[index],
manual_override: origins[index] === 'manual' ? { hops: [{ source_id: source.id, model_id }] } : null,
current: { source_id: source.id, model_id }, supply_state: 'ok',
chain: [{ source_id: source.id, model_id, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
})]));
const runtime = freshRuntimeProjection(readyRegion({
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
}));
diff --git a/ui/e2e/model-catalog/routeFixture.tsx b/ui/e2e/model-catalog/routeFixture.tsx
index 50ae65c3e..11faf5b38 100644
--- a/ui/e2e/model-catalog/routeFixture.tsx
+++ b/ui/e2e/model-catalog/routeFixture.tsx
@@ -28,7 +28,7 @@ const supply: AgentSupply = {
sources: { order: sources.map((source) => source.id), eligibility: sources.map((source) => ({ source_id: source.id, eligible: true })) },
};
const makeChain = (hops: RouteHop[], manual: boolean): AgentChain => ({
- contract_version: 18, backend, model_id: modelId,
+ contract_version: 19, backend, model_id: modelId,
manual_override: manual ? { hops } : null,
route_origin: manual ? 'manual' : origin === 'passthrough' ? 'passthrough' : 'automatic',
current: hops[0] ?? null, supply_state: hops.length ? 'ok' : 'interrupted',
diff --git a/ui/e2e/model-routing-origin.spec.ts b/ui/e2e/model-routing-origin.spec.ts
index 1ef1c0b9a..60ee5e970 100644
--- a/ui/e2e/model-routing-origin.spec.ts
+++ b/ui/e2e/model-routing-origin.spec.ts
@@ -102,7 +102,7 @@ test('MH-ROUTING-007 follow-defaults switch, undo, cancel, and save preserve exp
would_remove_hops: [{ backend: gateway.backend, menu_model: gateway.model, ...manual.hops[0], position: 1 }],
would_interrupt: [],
};
- expect(await refused.json()).toMatchObject({ ok: false, contract_version: 18, error: 'source_in_route_chain', ...plan });
+ expect(await refused.json()).toMatchObject({ ok: false, contract_version: 19, error: 'source_in_route_chain', ...plan });
expect((await api.agentChain(gateway.backend, gateway.model)).manual_override).toEqual(manual);
// The one question is its own modal over the chain the user was editing.
const guard = hub.dialogTitled(copy('guard.title.saveRoute', { menuModel: gateway.model }));
diff --git a/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts b/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
index 3a55b208f..da620ea55 100644
--- a/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
+++ b/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
@@ -92,7 +92,7 @@ for (const width of [1200, 390]) {
if (path === '/api/models/runtime/status') return answer({
ok: true,
runtime: {
- contract_version: 18, enabled: true, host_platform: 'linux',
+ contract_version: 19, enabled: true, host_platform: 'linux',
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: 'fixture', verified: true, health: 'ok' },
},
diff --git a/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts b/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
index e5189d7f4..f90fdb7f1 100644
--- a/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
+++ b/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
@@ -18,7 +18,7 @@ for (const [width,chosen] of [[1200,"claude"],[390,"claude"],[1200,"codex"]] as
const config=()=>({version:'v2',mode:'self_host',setup_completed:completed,setup_state:{needs_setup:!completed},capabilities:{model_hub:{enabled:true}},platforms:{primary:'slack',enabled:[]},runtime:{},agents:Object.fromEntries(['claude','codex','opencode'].map(b=>[b,{enabled:b!=='opencode',cli_path:b}])),agent:{default_cwd:'/fixture/work'},model_hub:{enabled:true,runtime_default_applied:true}});
const source={id:'src_fixture',kind:'api_key',vendor:'openai',display_name:'Fixture source',protocol:'openai_chat',supply_channel:'hub',billing:'metered',state:{status:'active'},masked_credential:'fixture-only',models:hops.map(h=>({id:h.model_id,display_name:h.model_id==='gpt-5'?'GPT-5':undefined,origin:'discovered',reasoning_efforts:[],reasoning_efforts_source:null})),last_discovered_at:null};
const supply=(b:string)=>({backend:b,cli_present:true,mode:'hub',menu_kind:'fixed',sources:{order:[source.id],eligibility:[{source_id:source.id,eligible:true}]},routes:{},builtin_models:[],catalog_models:[],menu:null,model_supply:[],named_agents:[{name:b,effective_model_id:agent(b).model,supply_status:saved[b].length?'ok':'unavailable'}],supply_status:saved[b].length?'ok':'unavailable'});
- const chain=(b:string,hs=saved[b])=>({contract_version:18,backend:b,model_id:agent(b).model,manual_override:hs.length?{hops:hs}:null,route_origin:hs.length?'manual':'automatic',current:hs[0]??null,chain:hs.map(h=>({...h,channel:'hub',health:'healthy',runnable:true,reason:null,retry_at:null})),supply_state:hs.length?'ok':'unavailable'});
+ const chain=(b:string,hs=saved[b])=>({contract_version:19,backend:b,model_id:agent(b).model,manual_override:hs.length?{hops:hs}:null,route_origin:hs.length?'manual':'automatic',current:hs[0]??null,chain:hs.map(h=>({...h,channel:'hub',health:'healthy',runnable:true,reason:null,retry_at:null})),supply_state:hs.length?'ok':'unavailable'});
await page.addInitScript(()=>localStorage.setItem('i18nextLng','en'));
await page.route(`${ORIGIN}/api/**`,async route=>{
const req=route.request(),path=new URL(req.url()).pathname;
@@ -34,7 +34,7 @@ for (const [width,chosen] of [[1200,"claude"],[390,"claude"],[1200,"codex"]] as
}
if(path==='/api/agents')return answer({ok:true,default_agent_name:defaultName,agents:[agent('claude'),agent('codex')]});
if(/^\/api\/agents\/(claude|codex)$/.test(path))return answer({ok:true,agent:agent(path.split('/').at(-1)!),default_agent_name:defaultName});
- if(path==='/api/models/runtime/status')return answer({ok:true,runtime:{contract_version:18,enabled:true,host_platform:'linux',manifest:{name:'cliproxyapi',resolution:'resolved',version:'fixture',source_sha:'a'.repeat(40),assets:[]},status:{installed_version:'fixture',verified:true,health:'ok'}}});
+ if(path==='/api/models/runtime/status')return answer({ok:true,runtime:{contract_version:19,enabled:true,host_platform:'linux',manifest:{name:'cliproxyapi',resolution:'resolved',version:'fixture',source_sha:'a'.repeat(40),assets:[]},status:{installed_version:'fixture',verified:true,health:'ok'}}});
if(path==='/api/models/sources')return answer({ok:true,sources:[source]});
if(path==='/api/models/agents')return answer({ok:true,agents:[supply('claude'),supply('codex')]});
if(/\/api\/models\/agents\/(claude|codex)\/chains$/.test(path)){
diff --git a/ui/e2e/onboarding-fidelity/provider-support.ts b/ui/e2e/onboarding-fidelity/provider-support.ts
index ad69c2e8c..07af8d3a3 100644
--- a/ui/e2e/onboarding-fidelity/provider-support.ts
+++ b/ui/e2e/onboarding-fidelity/provider-support.ts
@@ -129,7 +129,7 @@ const CONFIG = {
/** Installed, verified and serving: the screen's `gatewayIntent` reads `running` and
* starts no install, which is the state every proof below is about something else. */
const RUNTIME = {
- contract_version: 18,
+ contract_version: 19,
enabled: true,
host_platform: 'darwin',
manifest: {
diff --git a/ui/e2e/onboarding-fidelity/support.ts b/ui/e2e/onboarding-fidelity/support.ts
index 8a79120cd..c060a49ec 100644
--- a/ui/e2e/onboarding-fidelity/support.ts
+++ b/ui/e2e/onboarding-fidelity/support.ts
@@ -87,7 +87,7 @@ export async function serveProduct(page: Page) {
const backend = new URL(route.request().url()).pathname.split('/')[4];
return route.fulfill({ json: { ok: true, agent: { backend, mode: 'direct', sources: { order: [], eligibility: [] }, routes: {}, builtin_models: [], catalog_models: [], named_agents: [], menu: null, model_supply: [], supply_status: 'unavailable' } } });
});
- await page.route('**/api/models/runtime/status', (route) => route.fulfill({ json: { ok: true, runtime: { contract_version: 18, enabled: true, host_platform: 'linux', manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', assets: [] }, status: { installed_version: 'fixture', verified: true, health: 'ok' } } } }));
+ await page.route('**/api/models/runtime/status', (route) => route.fulfill({ json: { ok: true, runtime: { contract_version: 19, enabled: true, host_platform: 'linux', manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', assets: [] }, status: { installed_version: 'fixture', verified: true, health: 'ok' } } } }));
await page.route(`${ORIGIN}/status`, (route) => route.fulfill({ json: { state: 'running' } }));
await page.route('**/api/backend/*/connection', (route) => route.fulfill({ json: { ok: true, backend: new URL(route.request().url()).pathname.split('/').at(-2), installed: true, enabled: true, auth: 'none', application: 'applied', ready: false, entry_eligible: false } }));
await page.route('**/api/config', (route) => route.fulfill({ json: CONFIG }));
diff --git a/ui/e2e/workbench-general/geometry.spec.ts b/ui/e2e/workbench-general/geometry.spec.ts
index 38b480414..b0fc69432 100644
--- a/ui/e2e/workbench-general/geometry.spec.ts
+++ b/ui/e2e/workbench-general/geometry.spec.ts
@@ -48,7 +48,7 @@ const MODEL_HUB_AGENT = {
};
const MODEL_HUB_RUNTIME = {
- contract_version: 18,
+ contract_version: 19,
enabled: true,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'f'.repeat(40), assets: [] },
status: { installed_version: 'fixture', verified: true, listening: { host: '127.0.0.1', port: 43123 }, health: 'ok' },
diff --git a/ui/src/components/onboarding/AssistantSetup.test.tsx b/ui/src/components/onboarding/AssistantSetup.test.tsx
index 7d4d88b7e..99e2db3cd 100644
--- a/ui/src/components/onboarding/AssistantSetup.test.tsx
+++ b/ui/src/components/onboarding/AssistantSetup.test.tsx
@@ -50,7 +50,7 @@ const hubAgent = (enabled = true) => ({
system_prompt: null, created_at: '', metadata: { builtin_default: true },
});
const hubChain = (modelId: string) => ({
- contract_version: 18, backend: 'claude', model_id: 'opus-5',
+ contract_version: 19, backend: 'claude', model_id: 'opus-5',
manual_override: { hops: [{ source_id: 'src_a', model_id: modelId }] },
route_origin: 'manual', current: { source_id: 'src_a', model_id: modelId },
chain: [{ source_id: 'src_a', model_id: modelId, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
@@ -354,7 +354,7 @@ describe('assistant installation presentation', () => {
mock.api.getVibeAgent.mockResolvedValue({ ok: true, agent });
mock.models.listSources.mockResolvedValue([]);
const chain = {
- contract_version: 18, backend: 'claude', model_id: 'opus-5',
+ contract_version: 19, backend: 'claude', model_id: 'opus-5',
manual_override: { hops: [{ source_id: 'src_a', model_id: 'opus-5' }, { source_id: 'src_b', model_id: 'opus-5' }] },
route_origin: 'manual', current: { source_id: 'src_a', model_id: 'opus-5' },
chain: [
diff --git a/ui/src/components/onboarding/BuiltinAssistant.test.tsx b/ui/src/components/onboarding/BuiltinAssistant.test.tsx
index d4fe358c8..e9fe20d3c 100644
--- a/ui/src/components/onboarding/BuiltinAssistant.test.tsx
+++ b/ui/src/components/onboarding/BuiltinAssistant.test.tsx
@@ -65,7 +65,7 @@ const vibeyAgent = (model: string | null) => ({
system_prompt: null, created_at: '', metadata: { builtin_default: true, lock_delete: true },
});
const chain = (modelId: string) => ({
- contract_version: 18, backend: 'vibey', model_id: modelId,
+ contract_version: 19, backend: 'vibey', model_id: modelId,
manual_override: null, route_origin: 'automatic', current: { source_id: 'src_openai', model_id: modelId },
chain: [{ source_id: 'src_openai', model_id: modelId, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
supply_state: 'ok',
diff --git a/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx b/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
index 524939494..918c27768 100644
--- a/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
+++ b/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
@@ -79,7 +79,7 @@ const supply = (over: Partial<AgentSupply> & { backend: AgentSupply['backend'] }
});
const runtimeOf = (health: RuntimeHealth, over: Partial<RuntimeDependency> = {}): RuntimeDependency => ({
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'sha', assets: [] },
status: { verified: true, health },
...over,
diff --git a/ui/src/components/onboarding/providers/providerStage.test.ts b/ui/src/components/onboarding/providers/providerStage.test.ts
index b0af8ce2c..2196f9ac5 100644
--- a/ui/src/components/onboarding/providers/providerStage.test.ts
+++ b/ui/src/components/onboarding/providers/providerStage.test.ts
@@ -660,7 +660,7 @@ describe('adoptionBackend', () => {
});
const runtime = (health: RuntimeHealth, over: Partial<RuntimeDependency> = {}): RuntimeDependency => ({
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'sha', assets: [] },
status: { verified: true, health },
...over,
diff --git a/ui/src/components/settings/models/AgentCard.test.tsx b/ui/src/components/settings/models/AgentCard.test.tsx
index 14a76303e..1755f1ec6 100644
--- a/ui/src/components/settings/models/AgentCard.test.tsx
+++ b/ui/src/components/settings/models/AgentCard.test.tsx
@@ -17,7 +17,7 @@ import { freshRuntimeProjection } from './runtimeLifecycle';
import type { AgentSupply, RuntimeDependency, Source } from './types';
const runtime: RuntimeDependency = {
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
};
@@ -414,7 +414,7 @@ describe('AgentCard', () => {
['zh', 'Backup → claude-opus-4-6(已自动切换)', '打开 claude-opus-4-6 的路由 · Backup → claude-opus-4-6(已自动切换)'],
] as const)('derives and announces takeover from the exact current hop in %s', (lng, mappingCopy, accessibleName) => {
const key = modelChainKey('claude', 'claude-opus-4-6');
- render(<I18nextProvider i18n={localeInstance(lng)}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 18, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={localeInstance(lng)}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.getByText(/Backup/)).toBeTruthy();
expect(screen.getByTitle(mappingCopy)).toBeTruthy();
expect(screen.getByRole('button', { name: accessibleName })).toBeTruthy();
@@ -434,7 +434,7 @@ describe('AgentCard', () => {
sources={[source('src_b', 'Backup source')]}
chains={{
[key]: readyRegion({ manual_override: {hops:[{source_id:'src_b',model_id:'routed-opus'}]}, route_origin: "manual" as const,
- contract_version: 18,
+ contract_version: 19,
backend: 'claude',
model_id: 'claude-opus-4-6',
current: { source_id: 'src_b', model_id: 'routed-opus' },
@@ -467,7 +467,7 @@ describe('AgentCard', () => {
it('does not call a later current hop takeover unless the head is unavailable for cooldown', () => {
const key = modelChainKey('claude', 'claude-opus-4-6');
- render(<I18nextProvider i18n={i18n}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 18, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'native_cli', health: 'healthy', runnable: false, reason: 'native_cli_unavailable', retry_at: null }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'native_cli', health: 'healthy', runnable: false, reason: 'native_cli_unavailable', retry_at: null }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.getByText(/Backup/)).toBeTruthy();
expect(screen.queryByText(/takeover/i)).toBeNull();
});
@@ -475,7 +475,7 @@ describe('AgentCard', () => {
it('hides current and takeover projections while the runtime is stopped', () => {
const key = modelChainKey('claude', 'claude-opus-4-6');
const stopped = { ...runtime, status: { ...runtime.status, health: 'down' as const } };
- render(<I18nextProvider i18n={i18n}><RuntimeAgentCard runtime={freshRuntimeProjection(readyRegion(stopped))} agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 18, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><RuntimeAgentCard runtime={freshRuntimeProjection(readyRegion(stopped))} agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.queryByText(/Backup/)).toBeNull();
expect(screen.queryByText(/takeover/i)).toBeNull();
@@ -487,7 +487,7 @@ describe('AgentCard', () => {
const onOpenModels = vi.fn();
const key = modelChainKey('claude', 'claude-opus-4-6');
const directAgent: AgentSupply = { ...hubAgent, mode: 'direct', sources: null, routes: null, supply_status: null, model_supply: null };
- render(<I18nextProvider i18n={i18n}><AgentCard agents={[directAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 18, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={onOpenModels} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><AgentCard agents={[directAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={onOpenModels} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.queryByText(/Adjust priority/i)).toBeNull();
expect(screen.queryByRole('button', { name: /route chain/i })).toBeNull();
expect(screen.queryByText(/Backup/)).toBeNull();
diff --git a/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx b/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
index 4f6169f0d..5c88bf424 100644
--- a/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
+++ b/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
@@ -34,7 +34,7 @@ const CLAUDE_KEY: MigrationItem = {
};
const RUNTIME: RuntimeDependency = {
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: '1', verified: true, health: 'ok' },
};
diff --git a/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx b/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
index aaf3e0bbd..8789c42ce 100644
--- a/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
+++ b/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
@@ -17,7 +17,7 @@ const sources: Source[] = ['a', 'b'].map((id) => ({
}));
const hops = sources.map((source) => ({ source_id: source.id, model_id: 'gpt-test' }));
const makeChain = (backend: AgentSupply['backend'], routeOrigin: 'automatic' | 'passthrough' | 'manual'): AgentChain => ({
- contract_version: 18, backend, model_id: 'gpt-test', route_origin: routeOrigin,
+ contract_version: 19, backend, model_id: 'gpt-test', route_origin: routeOrigin,
manual_override: routeOrigin === 'manual' ? { hops } : null,
current: hops[0], supply_state: 'ok',
chain: hops.map((hop) => ({ ...hop, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null })),
diff --git a/ui/src/components/settings/models/RouteChainDialog.test.tsx b/ui/src/components/settings/models/RouteChainDialog.test.tsx
index 60f011922..02bdede96 100644
--- a/ui/src/components/settings/models/RouteChainDialog.test.tsx
+++ b/ui/src/components/settings/models/RouteChainDialog.test.tsx
@@ -57,7 +57,7 @@ const sources: Source[] = [
},
];
const chain: AgentChain = { manual_override: {hops:[{source_id:"src_a",model_id:"claude-opus-5"},{source_id:"src_b",model_id:"opus-5"}]}, route_origin: "manual" as const,
- contract_version: 18,
+ contract_version: 19,
backend: "claude",
model_id: "opus-5",
current: { source_id: "src_b", model_id: "opus-5" },
diff --git a/ui/src/components/settings/models/RouteRecordedTurn.test.tsx b/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
index a81d1811a..97d3f3b39 100644
--- a/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
+++ b/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
@@ -15,7 +15,7 @@ import { PERSISTED_TURN_CONTRACT_VERSIONS } from './types';
import type { RouteHop, TurnProvenance } from './types';
const record: TurnProvenance = {
- contract_version: 18, turn_id: 'turn-recorded', ts: '2026-09-05T15:00:00Z', agent: 'codex', requested_model_id: 'requested-model',
+ contract_version: 19, turn_id: 'turn-recorded', ts: '2026-09-05T15:00:00Z', agent: 'codex', requested_model_id: 'requested-model',
outcome: 'failed_terminal', failed_attempts: [], served: null, canceled_attempt: null, model_supply_state: null, blockers: [],
terminal_error: { source_id: 'src_historical', configured_model_id: 'historical-model', channel: 'hub', reason: 'invalid_parameter', stream_started: false, http_status: 404, upstream_error_code: 'model_not_found' },
};
diff --git a/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx b/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
index 8c687b82e..3e31e06d5 100644
--- a/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
+++ b/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
@@ -31,7 +31,7 @@ const runtime = (
? 'unresolved' as const
: hostPlatform === 'linux-amd64' ? 'unsupported' as const : 'resolved' as const;
return {
- contract_version: 18,
+ contract_version: 19,
...(hostPlatform === undefined ? {} : { host_platform: hostPlatform }),
manifest: resolution === 'unresolved'
? { name: 'cliproxyapi', resolution, assets: [] }
diff --git a/ui/src/components/settings/models/SearchServiceParts.tsx b/ui/src/components/settings/models/SearchServiceParts.tsx
index b9ea8d5b1..ad6616659 100644
--- a/ui/src/components/settings/models/SearchServiceParts.tsx
+++ b/ui/src/components/settings/models/SearchServiceParts.tsx
@@ -7,9 +7,11 @@ import { Select } from '@/components/ui/select';
import { cn } from '@/lib/utils';
import { ToggleSwitch } from '../SettingsPrimitives';
import { Field } from './dialogFields';
-import { formatMonthDay, formatSmallUsd } from './format';
+import { atLeast, formatCost, formatCount, formatMonthDay, formatSmallUsd, formatUsd } from './format';
+import { foldRegionRead, regionFailed, type RegionRead } from './regionRead';
import { serviceSettings } from './searchServices';
import { sourceStatePresentation } from './sourceStatePresentation';
+import { usageHasNoPrice, type ServiceMonth } from './usageProjection';
import { VendorGlyph } from './vendorGlyph';
import type { HostedExecutorCandidate, HostedSearchServiceVendor, HostedServiceListPrice, HostedToolPut, HostedWebSearchToolStatus, Source } from './types';
@@ -84,6 +86,35 @@ export const SearchVendorFacts: React.FC<{ vendor: HostedSearchServiceVendor }>
</>;
};
+/** This month's requests and their list valuation, with the vendors' own figure beside it, never in it. */
+const ServiceMonthLine: React.FC<{ month: RegionRead<ServiceMonth>; onOpenUsage?: () => void }> = ({ month, onOpenUsage }) => {
+ const { t, i18n } = useTranslation();
+ const usage = foldRegionRead<ServiceMonth, ServiceMonth | null>(month, {
+ loading: () => null, ready: (data) => data, unread: () => null, degraded: (data) => data,
+ });
+ if (usage === null && !regionFailed(month)) return null;
+ const parts = usage === null ? [t('settings.models.usage.failure')] : [
+ t('settings.models.searchServices.monthRequests', {
+ count: usage.totals.requests,
+ requests: atLeast(formatCount(usage.totals.requests, i18n.language), usage.partial),
+ }),
+ // Without a price table the report carries counts only.
+ ...(usage.priced ? [usageHasNoPrice(usage.totals)
+ ? t('settings.models.usage.cost.noPrice')
+ : t('settings.models.searchServices.monthEstimate', {
+ usd: formatCost(usage.totals.api_cost_usd ?? 0, usage.totals.api_cost_lower_bound || usage.partial, i18n.language),
+ })] : []),
+ ...(usage.priced && usage.totals.reported_requests > 0
+ ? [t('settings.models.searchServices.monthReported', { usd: formatUsd(usage.totals.reported_usd ?? 0, i18n.language) })]
+ : []),
+ ];
+ return <p className="model-hub-tool-note flex flex-wrap items-center gap-x-2 gap-y-1" data-service-month={usage?.month}>
+ <span className="font-semibold text-foreground">{t('settings.models.searchServices.month')}</span>
+ <span>{parts.join(' · ')}</span>
+ {onOpenUsage && <button type="button" onClick={onOpenUsage} className="model-hub-action-mint shrink-0 font-semibold">{t('settings.models.searchServices.openUsage')}</button>}
+ </p>;
+};
+
/** Only per-field patches leave this section; effective defaults are never echoed into saved overrides. */
export const SearchServiceSettings: React.FC<{
source: Source;
@@ -92,7 +123,10 @@ export const SearchServiceSettings: React.FC<{
pending: boolean;
onSave: (body: HostedToolPut) => void;
onRetry: (sourceId: string) => void;
-}> = ({ source, tool, vendor, pending, onSave, onRetry }) => {
+ /** Present only while the Tools read lists this Source as a search service. */
+ month?: RegionRead<ServiceMonth>;
+ onOpenUsage?: () => void;
+}> = ({ source, tool, vendor, pending, onSave, onRetry, month, onOpenUsage }) => {
const { t } = useTranslation();
const settings = serviceSettings(tool, vendor, source.id);
const candidate = tool.executor_candidates.find((row) => row.source_id === source.id);
@@ -112,5 +146,6 @@ export const SearchServiceSettings: React.FC<{
</Field>
<p className="model-hub-tool-note">{t('settings.models.searchServices.settingsNote')}</p>
<SearchServicePrice price={vendor.price} />
+ {month && <ServiceMonthLine month={month} onOpenUsage={onOpenUsage} />}
</section>;
};
diff --git a/ui/src/components/settings/models/SearchServices.test.tsx b/ui/src/components/settings/models/SearchServices.test.tsx
index 8c3541fbd..b60ad527f 100644
--- a/ui/src/components/settings/models/SearchServices.test.tsx
+++ b/ui/src/components/settings/models/SearchServices.test.tsx
@@ -20,7 +20,7 @@ import { ACTIVE_SEARCH, INACTIVE_SEARCH, SEARCH_SOURCES } from './searchServices
import { SourceDetailPanel } from './SourceDetailPanel';
import { SourcesCard } from './SourcesCard';
import { ToolsTab } from './ToolsTab';
-import type { HostedServiceExecutorCandidate, HostedWebSearchToolStatus, Source } from './types';
+import type { HostedServiceExecutorCandidate, HostedWebSearchToolStatus, Source, UsageReport } from './types';
const wrap = (element: React.ReactElement, lng = 'en') => <I18nextProvider i18n={i18n.cloneInstance({ lng })}><ToastProvider>{element}</ToastProvider></I18nextProvider>;
const tab = (tool = ACTIVE_SEARCH) => {
@@ -31,16 +31,32 @@ const tab = (tool = ACTIVE_SEARCH) => {
const view = render(wrap(<ToolsTab read={readyRegion({ tools: [tool] })} sources={SEARCH_SOURCES} pending={new Set()} onSave={onSave} onClear={vi.fn()} onRetry={vi.fn()} onOpenService={onOpenService} onAddService={onAddService} onRetryService={onRetryService} />));
return { ...view, onSave, onOpenService, onRetryService, onAddService };
};
+// A daily report whose host month (`to_day`) holds one Exa day; the previous month's last day stays out.
+const MONTH_REPORT: UsageReport = {
+ window_days: 60, from_day: '2026-08-23', to_day: '2026-10-21', window_key: '60d', granularity: 'day',
+ from_at: '2026-08-23T00:00:00+08:00', to_at: '2026-10-21T12:00:00+08:00',
+ totals: { requests: 0, token_reports: 0, input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 },
+ sources: [], services: [], days: [], pricing: { currency: 'USD', price_table_date: '2026-10-19', service_price_date: '2026-10-19' },
+ buckets: ['2026-09-30', '2026-10-05'].map((key) => ({
+ key, start_at: `${key}T00:00:00+08:00`, end_at: `${key}T23:59:59+08:00`, history_complete: true,
+ rows: [{
+ kind: 'service', source_id: 'src_exa000001', service_id: 'exa/search', requests: 3, billable_requests: 2, uncertain_requests: 1,
+ reported_requests: 2, reported_usd: 0.0135, api_cost_usd: 0.014, api_cost_lower_bound: true,
+ }],
+ })),
+};
const detail = (source: Source, tool = ACTIVE_SEARCH, serviceView = true) => {
const onSaveSearch = vi.fn();
const onRetryService = vi.fn();
+ const onOpenUsage = vi.fn();
+ const readUsage = vi.spyOn(modelsApi, 'getUsageSummary').mockResolvedValue(MONTH_REPORT);
const settle: SourceMutationSettlement = {
source: vi.fn().mockResolvedValue(null), gone: vi.fn().mockResolvedValue(null), unread: vi.fn().mockResolvedValue(null), release: vi.fn(),
readInventory: vi.fn().mockResolvedValue({ snapshot: 1, sources: [source] }),
};
const trackMutation: TrackSourceMutation = (work) => work(source, settle);
- const view = render(wrap(<SourceDetailPanel source={source} hostedTools={readyRegion({ tools: [tool] })} onSaveSearch={onSaveSearch} onRetryService={onRetryService} serviceView={serviceView} onManageSource={vi.fn()} trackMutation={trackMutation} onReauth={vi.fn()} onMutationCommitted={async (commit) => { await commit.settle(); }} />));
- return { ...view, onSaveSearch, onRetryService, settle };
+ const view = render(wrap(<SourceDetailPanel source={source} hostedTools={readyRegion({ tools: [tool] })} onSaveSearch={onSaveSearch} onRetryService={onRetryService} serviceView={serviceView} onManageSource={vi.fn()} onOpenUsage={onOpenUsage} trackMutation={trackMutation} onReauth={vi.fn()} onMutationCommitted={async (commit) => { await commit.settle(); }} />));
+ return { ...view, onSaveSearch, onRetryService, onOpenUsage, readUsage, settle };
};
const addDialog = (tool = ACTIVE_SEARCH) => {
const onAdded = vi.fn();
@@ -161,7 +177,7 @@ describe('search Source detail', () => {
detail(SEARCH_SOURCES[0]);
expect(screen.getByText('Search service · does not provide models')).toBeTruthy();
expect(screen.queryByRole('button', { name: /Refetch|Test|Add model|Re-enable/ })).toBeNull();
- expect(screen.queryByText(/this month|page content|full page/i)).toBeNull();
+ expect(screen.queryByText(/page content|full page/i)).toBeNull();
await userEvent.click(screen.getByRole('button', { name: 'Replace key' }));
expect(screen.getByRole('dialog', { name: 'Replace the API key for “Tavily”' })).toBeTruthy();
await userEvent.click(within(screen.getByRole('dialog')).getAllByRole('button', { name: 'Cancel' }).at(-1)!);
@@ -171,6 +187,26 @@ describe('search Source detail', () => {
await waitFor(() => expect(remove).toHaveBeenCalledWith('src_tavily001', undefined));
});
+ it.each([
+ ['listed', ACTIVE_SEARCH, true],
+ ['dormant', INACTIVE_SEARCH, false],
+ ['unlisted', { ...ACTIVE_SEARCH, executor_candidates: ACTIVE_SEARCH.executor_candidates.filter((row) => row.source_id !== 'src_exa000001') }, false],
+ ] as const)('MH-USAGE-038: reads this month only for a %s search service, apart from the Usage tab', async (_, tool, listed) => {
+ const { readUsage, onOpenUsage } = detail(SEARCH_SOURCES[1], tool);
+ if (!listed) {
+ await waitFor(() => expect(screen.getByRole('heading', { name: 'Exa' })).toBeTruthy());
+ expect(readUsage).not.toHaveBeenCalled();
+ expect(screen.queryByText('This month')).toBeNull();
+ return;
+ }
+ // Its own daily read, never the tab's window; the vendors' figure stands beside the list estimate.
+ expect(readUsage.mock.calls).toEqual([['60d']]);
+ const line = (await screen.findByText('This month')).closest('p')!;
+ expect(line.textContent).toBe('This month3 requests · API list-price estimate ≥ $0.01 · vendor-reported $0.01View usage');
+ await userEvent.click(within(line).getByRole('button', { name: 'View usage' }));
+ expect(onOpenUsage).toHaveBeenCalledOnce();
+ });
+
it.each([null, '2026-12-01T10:00:00Z'])('offers retry exactly when cooldown_until=%s on both row and detail', async (cooldown_until) => {
const candidate: HostedServiceExecutorCandidate = { ...(ACTIVE_SEARCH.executor_candidates[1] as HostedServiceExecutorCandidate), cooldown_until };
const tool = { ...ACTIVE_SEARCH, executor_candidates: [candidate] };
diff --git a/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx b/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
index a4547d843..afadeccde 100644
--- a/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
+++ b/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
@@ -49,7 +49,7 @@ const manifest = {
} satisfies RuntimeManifest;
const runtime: RuntimeDependency = {
- contract_version: 18,
+ contract_version: 19,
manifest,
status: { installed_version: '1', verified: true, health: 'ok' },
};
@@ -120,7 +120,7 @@ const takeoverAgent: AgentSupply = {
};
const takeoverChain: AgentChain = { manual_override: {hops:[{source_id:'src_head',model_id:'gpt-5.6-sol'},{source_id:'src_relay',model_id:'gpt-5.6-sol'}]}, route_origin: "manual" as const,
- contract_version: 18,
+ contract_version: 19,
backend: 'codex',
model_id: 'gpt-5.6-sol',
current: { source_id: 'src_relay', model_id: 'gpt-5.6-sol' },
@@ -152,6 +152,7 @@ const usageSummary: UsageReport = {
output_tokens: 4120,
models: [{ model_id: 'claude-opus-4-6', label: 'claude-opus-4-6', requests: 12, token_reports: 12, input_tokens: 148230, cached_input_tokens: 96010, output_tokens: 4120 }],
}],
+ services: [],
days: [{ day: '2026-08-18', requests: 12, token_reports: 12, input_tokens: 148230, cached_input_tokens: 96010, output_tokens: 4120 }],
window_key: '24h',
granularity: 'hour',
@@ -223,7 +224,7 @@ const routedHubAgent: AgentSupply = {
const routedChain: AgentChain = {
manual_override: { hops: [{ source_id: retainedSource.id, model_id: routedModelId }] },
route_origin: 'manual' as const,
- contract_version: 18,
+ contract_version: 19,
backend: 'claude',
model_id: routedModelId,
current: { source_id: retainedSource.id, model_id: routedModelId },
@@ -2830,6 +2831,18 @@ describe('SettingsModelsPage tools region', () => {
expect(await screen.findByRole('dialog', { name: 'Add search service' })).toBeTruthy();
});
+ it('MH-USAGE-038: leaves a service detail for the Usage tab, whose window the detail read never moved', async () => {
+ renderPage(SEARCH_SOURCES, undefined, runtime, { tools: [ACTIVE_SEARCH] });
+ await screen.findByRole('button', { name: 'Add provider' });
+ await userEvent.click(screen.getByRole('tab', { name: /^Tools$|^工具$/ }));
+ await userEvent.click(await screen.findByRole('button', { name: 'Exa' }));
+ await userEvent.click(await screen.findByRole('button', { name: 'View usage' }));
+ await waitFor(() => expect(screen.getByRole('tab', { name: /^Usage$/ }).getAttribute('aria-selected')).toBe('true'));
+ await waitFor(() => expect(vi.mocked(modelsApi.getUsageSummary).mock.calls).toEqual([['60d'], ['24h']]));
+ expect(screen.getByRole('radio', { name: '24 hours', checked: true })).toBeTruthy();
+ expect(screen.queryByRole('heading', { name: 'Exa' })).toBeNull();
+ });
+
it('MH-HOSTED-UI-005: reads activation on Sources without gating first paint, then refreshes when its surface changes', async () => {
renderPage([retainedSource]);
await screen.findByText('Retained source');
diff --git a/ui/src/components/settings/models/SettingsModelsPage.tsx b/ui/src/components/settings/models/SettingsModelsPage.tsx
index 7d77bac44..4392a80e8 100644
--- a/ui/src/components/settings/models/SettingsModelsPage.tsx
+++ b/ui/src/components/settings/models/SettingsModelsPage.tsx
@@ -1768,6 +1768,7 @@ export const SettingsModelsPage: React.FC = () => {
source={selectedSource}
serviceView={serviceDetailView}
onManageSource={() => setServiceDetailView(false)}
+ onOpenUsage={() => { selectSource(null); setTab('usage'); }}
onSaveSearch={(body) => void hostedTools.save('web_search', body)}
onRetryService={(sourceId) => void hostedTools.retryService(sourceId)}
hostedTools={hostedTools.read}
diff --git a/ui/src/components/settings/models/SourceDetailPanel.tsx b/ui/src/components/settings/models/SourceDetailPanel.tsx
index 67b74e37d..9e5622f8e 100644
--- a/ui/src/components/settings/models/SourceDetailPanel.tsx
+++ b/ui/src/components/settings/models/SourceDetailPanel.tsx
@@ -19,7 +19,7 @@ import { GuardDialog } from './GuardDialog';
import { GuardImpact } from './GuardImpact';
import { HostedCapabilityChips } from './HostedCapabilityChips';
import { modelCapabilities } from './hostedTools';
-import { serviceVendorForSource, webSearchTool } from './searchServices';
+import { searchServicesActive, serviceVendorForSource, webSearchTool } from './searchServices';
import { SearchServiceSettings, SearchVendorGlyph } from './SearchServiceParts';
import { confirmGuardPlan, sendAgreed, unansweredRefusal } from './guardedWrite';
import { ModelHubInfoHint } from './ModelHubInfoHint';
@@ -56,7 +56,8 @@ import {
type TrackSourceMutation,
} from './mutationSettlement';
import { reconcileUnknownWrite } from './reconcileUnknownWrite';
-import { foldRegionRead, regionFailed, type RegionRead } from './regionRead';
+import { foldRegionRead, loadingRegion, readRegion, regionFailed, type RegionRead } from './regionRead';
+import { serviceMonthUsage, type ServiceMonth } from './usageProjection';
import { REPAIR_DESTINATION, REPAIR_LABEL_KEY, reauthBodyKey, reauthCost, repairAction, wasBlocked } from './repair';
import { activeSourceAdoption, sourceStatePresentation } from './sourceStatePresentation';
import { useDeadlineClock } from './useDeadlineClock';
@@ -151,6 +152,25 @@ const committedPlan = (hops: RouteHopRef[], gaps: SupplyGap[]): ManageGuardPlan
const NO_TOOLS: ReadonlySet<HostedToolName> = new Set();
+/** A candidate service's host-local month, read in the keyed detail child only while it is visible. */
+function useServiceMonth(sourceId: string): RegionRead<ServiceMonth> {
+ const [month, setMonth] = React.useState<RegionRead<ServiceMonth>>(loadingRegion);
+ React.useEffect(() => {
+ let current = true;
+ void readRegion(async () => serviceMonthUsage(await modelsApi.getUsageSummary('60d'), sourceId))
+ .then((read) => { if (current) setMonth(read); });
+ return () => { current = false; };
+ }, [sourceId]);
+ return month;
+}
+
+type SearchSettingsProps = React.ComponentProps<typeof SearchServiceSettings>;
+
+const ServiceMonthSearchSettings: React.FC<Omit<SearchSettingsProps, 'month'>> = (props) => {
+ const month = useServiceMonth(props.source.id);
+ return <SearchServiceSettings {...props} month={month} />;
+};
+
type SourceReconciliation =
| { kind: 'source'; source: Source }
| { kind: 'gone'; sources: Source[]; snapshot: number };
@@ -188,7 +208,9 @@ export const SourceDetailPanel: React.FC<{
/** A model Source reached from Tools shows its search detail, without model removal. */
serviceView?: boolean;
onManageSource?: () => void;
-}> = ({ source, trackMutation, onReauth, onMutationCommitted, headingRef, activeBackends, hostedTools, onRetryHostedTools, hostedPending, onClearHostedRefusal, onSaveSearch, onRetryService, serviceView, onManageSource }) => {
+ /** Leave the detail for the Usage tab, from a search service's monthly line. */
+ onOpenUsage?: () => void;
+}> = ({ source, trackMutation, onReauth, onMutationCommitted, headingRef, activeBackends, hostedTools, onRetryHostedTools, hostedPending, onClearHostedRefusal, onSaveSearch, onRetryService, serviceView, onManageSource, onOpenUsage }) => {
const { t, i18n } = useTranslation();
const { showToast } = useToast();
const detailsHidden = useSourceDetailsHidden();
@@ -226,7 +248,24 @@ export const SourceDetailPanel: React.FC<{
const searchTool = webSearchTool(capabilityStatus);
const serviceVendor = serviceVendorForSource(searchTool, source.id);
const serviceDetail = Boolean(serviceVendor && (source.protocol === 'search' || serviceView));
- const searchSettings = searchTool && serviceVendor && onSaveSearch && onRetryService ? <SearchServiceSettings source={source} tool={searchTool} vendor={serviceVendor} pending={busy || (hostedPending?.has('web_search') ?? false)} onSave={onSaveSearch} onRetry={onRetryService} /> : null;
+ // Usage, like the Tools rows, waits for the read to list this Source as a search service.
+ const serviceCandidate = searchServicesActive(searchTool)
+ && Boolean(searchTool?.executor_candidates.some((row) => row.kind === 'service' && row.source_id === source.id));
+ let searchSettings: React.ReactNode = null;
+ if (searchTool && serviceVendor && onSaveSearch && onRetryService) {
+ const settingsProps = {
+ source,
+ tool: searchTool,
+ vendor: serviceVendor,
+ pending: busy || (hostedPending?.has('web_search') ?? false),
+ onSave: onSaveSearch,
+ onRetry: onRetryService,
+ onOpenUsage,
+ };
+ searchSettings = serviceCandidate
+ ? <ServiceMonthSearchSettings key={source.id} {...settingsProps} />
+ : <SearchServiceSettings {...settingsProps} month={undefined} />;
+ }
const capabilities = new Map(models.map((model) => [
model.id,
capabilityStatus ? modelCapabilities(capabilityStatus, source.id, model.id) : [],
diff --git a/ui/src/components/settings/models/SupplyGraph.test.ts b/ui/src/components/settings/models/SupplyGraph.test.ts
index 34c26fc20..67660ddae 100644
--- a/ui/src/components/settings/models/SupplyGraph.test.ts
+++ b/ui/src/components/settings/models/SupplyGraph.test.ts
@@ -7,7 +7,7 @@ import { buildSupplyRelations as buildRelations } from './supplyRelations';
import type { AgentChain, AgentSupply, RuntimeDependency, Source } from './types';
const runtime: RuntimeDependency = {
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
};
@@ -47,7 +47,7 @@ const agent: AgentSupply = {
};
const chain = (current: string, headHealth: AgentChain['chain'][number]['health'] = 'healthy', headRunnable = true, reason: AgentChain['chain'][number]['reason'] = null): AgentChain => ({ manual_override: {hops:[{source_id:'native',model_id:'model-a'},{source_id:'relay',model_id:'model-a'},{source_id:'unused',model_id:'model-a'}]}, route_origin: "manual" as const,
- contract_version: 18,
+ contract_version: 19,
backend: 'claude',
model_id: 'model-a',
current: { source_id: current, model_id: 'model-a' },
diff --git a/ui/src/components/settings/models/UsageTab.test.tsx b/ui/src/components/settings/models/UsageTab.test.tsx
index ecab8bae2..a8770a56e 100644
--- a/ui/src/components/settings/models/UsageTab.test.tsx
+++ b/ui/src/components/settings/models/UsageTab.test.tsx
@@ -8,9 +8,18 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
import en from '../../../i18n/en.json';
import zh from '../../../i18n/zh.json';
import { readyRegion } from './regionRead';
-import type { UsageBucket, UsageBucketRow, UsageCounters, UsageReport, UsageWindowKey } from './types';
+import type {
+ ServiceUsage,
+ UsageBucket,
+ UsageBucketEntry,
+ UsageBucketRow,
+ UsageCounters,
+ UsageReport,
+ UsageServiceBucketRow,
+ UsageWindowKey,
+} from './types';
import { UsageTab } from './UsageTab';
-import { buildUsageCsv, csvCell } from './usageCsv';
+import { buildUsageCsv, csvCell, type UsageCsvHeaders } from './usageCsv';
const i18n = createInstance();
void i18n.use(initReactI18next).init({
@@ -38,7 +47,7 @@ const row = (over: Partial<UsageBucketRow> = {}): UsageBucketRow => ({
const bucket = (
key: string,
- rows: UsageBucketRow[] = [row()],
+ rows: UsageBucketEntry[] = [row()],
over: Partial<UsageBucket> = {},
): UsageBucket => ({
key,
@@ -61,6 +70,7 @@ const report = (over: Partial<UsageReport> = {}): UsageReport => ({
...counters({ requests: 6, token_reports: 6, input_tokens: 300, cached_input_tokens: 75, output_tokens: 120 }),
models: [{ model_id: 'model-a', label: 'Shared model', ...counters({ requests: 6, token_reports: 6, input_tokens: 300, cached_input_tokens: 75, output_tokens: 120 }) }],
}],
+ services: [],
days: [],
window_key: '24h',
granularity: 'hour',
@@ -83,6 +93,11 @@ const draw = (
</I18nextProvider>,
);
+const CSV_HEADERS = Object.fromEntries([
+ 'bucketKey', 'startAt', 'endAt', 'historyComplete', 'sourceId', 'modelId', 'ledgerKey', 'sourceLabel', 'modelLabel',
+ 'requests', 'tokenReports', 'inputTokens', 'nonCachedInputTokens', 'cachedInputTokens', 'outputTokens', 'totalTokens',
+].map((key) => [key, key])) as UsageCsvHeaders;
+
afterEach(cleanup);
describe('UsageTab', () => {
@@ -604,6 +619,65 @@ describe('UsageTab', () => {
}
});
+ it('MH-USAGE-037: tables search services below the models, adding only their cost to the API-price total', async () => {
+ const search = (over: Partial<UsageServiceBucketRow> = {}): UsageServiceBucketRow => ({
+ kind: 'service', source_id: 'src_exa', service_id: 'exa/search', requests: 3, billable_requests: 2, uncertain_requests: 1,
+ reported_requests: 2, reported_usd: 0.0135, api_cost_usd: 0.014, api_cost_lower_bound: true, ...over,
+ });
+ const listing = (entry: UsageServiceBucketRow, over: Partial<ServiceUsage> = {}): ServiceUsage => ({
+ source_id: entry.source_id, service_id: entry.service_id, label: null, service_label: null, last_metered_at: null,
+ requests: entry.requests, billable_requests: entry.billable_requests, uncertain_requests: entry.uncertain_requests,
+ reported_requests: entry.reported_requests, ...over,
+ });
+ const exa = search();
+ // A deleted Source, on a service a later catalog no longer prices.
+ const retired = search({ source_id: 'src_gone', service_id: 'retired/search', requests: 1, billable_requests: 1, uncertain_requests: 0, reported_requests: 0, reported_usd: 0, api_cost_usd: 0 });
+ const value = pricedReport();
+ value.buckets = [bucket('00', [...value.buckets[0]!.rows, exa, retired])];
+ value.services = [listing(exa, { label: 'Exa key', service_label: 'Exa', priced: true }), listing(retired, { priced: false })];
+ value.pricing = { ...value.pricing!, service_price_date: '2026-10-19' };
+ const { container } = draw(value);
+
+ const stats = container.querySelector('.model-hub-usage-stat-grid--priced')!;
+ // The model calls alone, and every cost beside the vendors' own figure.
+ expect(stats.textContent).toContain('Requests4');
+ expect(stats.textContent).toContain('≥ $0.51');
+ expect(stats.textContent).toContain('Vendors reported $0.01');
+ expect(stats.textContent).toContain('1 search request has no price and is left out');
+ const services = within(screen.getByRole('region', { name: /^Search services/ }));
+ const rowsOf = (scope: HTMLElement) => [...scope.querySelectorAll('tbody tr')].map((line) => [...line.children].map((cell) => cell.textContent));
+ expect(rowsOf(services.getByRole('table'))).toEqual([
+ ['Exa keyExa', '3', '2+1 with unknown billing', '≥ $0.01', '$0.01'],
+ ['Removed providersUsage kept after these providers were deleted', '1', '1', 'No price yet', '—'],
+ ]);
+ expect(services.getByRole('table').querySelector('tfoot')!.textContent).toBe('Total43+1 with unknown billing≥ $0.01$0.01');
+ expect(services.getByText(/Search prices from 2026-10-19/)).toBeTruthy();
+ const details = within(screen.getByRole('region', { name: /^Exact usage details/ }));
+ expect(details.queryByText(/Exa key|Removed providers/)).toBeNull();
+ // Exports and the model filter are model usage only; a tool-only Source is a Source.
+ expect(buildUsageCsv(value, { sourceIds: [], modelKeys: [] }, null, CSV_HEADERS, 'Unknown model')).not.toContain('search');
+ await userEvent.click(screen.getByRole('button', { name: 'All Source' }));
+ const options = (label: string) => within(screen.getByRole('listbox', { name: label })).getAllByRole('option').map((option) => option.textContent);
+ expect(options('Source')).toEqual(['All Source', 'Claude', 'Relay', 'Exa key', 'Removed providers']);
+ await userEvent.keyboard('{Escape}');
+ await userEvent.click(screen.getByRole('button', { name: 'All Model' }));
+ expect(options('Model')).toEqual(['All Model', 'Claude · Opus', 'Relay · Relay model']);
+ await userEvent.click(screen.getByRole('option', { name: 'Claude · Opus' }));
+ expect(services.getByText('No matching usage')).toBeTruthy();
+ expect(stats.textContent).toContain('$0.50');
+ cleanup();
+
+ // Search alone is usage, and without a price table it reads counts only.
+ const counted: UsageServiceBucketRow = {
+ kind: 'service', source_id: 'src_exa', service_id: 'exa/search', requests: 3, billable_requests: 2, uncertain_requests: 1, reported_requests: 2,
+ };
+ const only = draw(report({ sources: [], services: [listing(counted, { label: 'Exa key' })], buckets: [bucket('00', [counted])] }));
+ expect(screen.queryByText('No usage in this window')).toBeNull();
+ expect(only.container.querySelector('.model-hub-usage-stat-grid')!.textContent).toContain('Requests0');
+ const countsOnly = within(screen.getByRole('region', { name: /^Search services/ })).getByRole('table');
+ expect([...countsOnly.querySelectorAll('thead th')].map((cell) => cell.textContent)).toEqual(['Source / service', 'Requests', 'Billable']);
+ });
+
it('renders exact accounting and preserves source/model pair rows', () => {
const second = row({ source_id: 'source-b', model_id: 'model-a' });
const value = report({
diff --git a/ui/src/components/settings/models/UsageTab.tsx b/ui/src/components/settings/models/UsageTab.tsx
index 99e60328e..953eefea7 100644
--- a/ui/src/components/settings/models/UsageTab.tsx
+++ b/ui/src/components/settings/models/UsageTab.tsx
@@ -25,6 +25,7 @@ import { foldRegionRead, regionFailed, type RegionRead } from './regionRead';
import type { UsageCounters, UsageReport, UsageWindowKey } from './types';
import {
aggregateCounters,
+ aggregateServiceRows,
costIsFloor,
costIsUnpriced,
filterBucketRows,
@@ -35,11 +36,16 @@ import {
formatBucketHeading,
formatBucketRange,
emptyCounters,
+ isModelRow,
+ isServiceRow,
+ metricRows,
reportHasPartialHistory,
reportIsPriced,
reportHasUnknownTokens,
resolveUsageFilter,
seriesFor,
+ serviceUsageRows,
+ unpricedServices,
usageCachedInputShare,
usageIdentities,
usageIsEmpty,
@@ -49,6 +55,7 @@ import {
usageNonCachedInput,
usageReportShortfall,
usageTokensAreKnown,
+ type ServiceTotals,
type UsageFilter,
type UsageGroup,
type UsageMetric,
@@ -94,6 +101,7 @@ const useUsageTranslation = () => {
const usageText = (t: UsageTranslate): UsageText => ({
unknownModel: t('settings.models.usage.unknownModel'),
removedSources: t('settings.models.usage.removedSources'),
+ searchServices: t('settings.models.usage.services.title'),
});
const useCount = () => {
@@ -359,11 +367,12 @@ function UsageChart({
? requestedIndex
: null;
const bars = report.window_key === '30d' || report.window_key === '60d';
- const { unknownModel, removedSources } = usageText(t);
+ const { unknownModel, removedSources, searchServices } = usageText(t);
const series = React.useMemo(
- () => seriesFor(report, filter, group, metric, { unknownModel, removedSources }),
- [filter, group, metric, removedSources, report, unknownModel],
+ () => seriesFor(report, filter, group, metric, { unknownModel, removedSources, searchServices }),
+ [filter, group, metric, removedSources, report, searchServices, unknownModel],
);
+ const unpriced = React.useMemo(() => unpricedServices(report), [report]);
const labels = React.useMemo(() => new Map(series.map((item) => [
item.key,
item.key === 'total'
@@ -404,8 +413,8 @@ function UsageChart({
: index / Math.max(1, bucketCount - 1)) * plotWidth;
const y = (value: number) => top + plotHeight * (1 - value / max);
const bucket = activeIndex === null || activeIndex < 0 ? null : report.buckets[activeIndex];
- const bucketRows = bucket === null ? [] : filterBucketRows(bucket, filter);
- const bucketTotals = aggregateCounters(bucketRows);
+ const bucketRows = bucket === null ? [] : metricRows(filterBucketRows(bucket, filter), metric);
+ const bucketTotals = aggregateCounters(bucketRows, unpriced);
const activeValue = bucket && !bucket.history_complete && bucketRows.length === 0
? null
: usageMetricValue(bucketTotals, metric);
@@ -871,7 +880,7 @@ function UsageChart({
<div className="model-hub-usage-tooltip-total">
<strong>{activeValue === null
? t('settings.models.usage.blank')
- : costIsUnpriced(bucketRows, metric)
+ : costIsUnpriced(bucketRows, metric, unpriced)
? noPriceText(report, t)
: atLeast(format(activeValue), costIsFloor(bucketRows, metric))}</strong>
<span>{metricLabel(metric, t)}</span>
@@ -890,7 +899,7 @@ function UsageChart({
</div>
<div className="model-hub-usage-tooltip-foot">
<span>
- {bucket.history_complete || bucketRows.length > 0 ? count(bucketTotals.requests) : t('settings.models.usage.blank')}
+ {bucket.history_complete || bucketRows.some(isModelRow) ? count(bucketTotals.requests) : t('settings.models.usage.blank')}
{' '}
{t('settings.models.usage.requests.unit')}
</span>
@@ -925,7 +934,7 @@ function tableRows(
t: UsageTranslate,
): TableRow[] {
const buckets = pinnedKey === null ? report.buckets : report.buckets.filter((bucket) => bucket.key === pinnedKey);
- const rows = buckets.flatMap((bucket) => filterBucketRows(bucket, filter));
+ const rows = buckets.flatMap((bucket) => filterBucketRows(bucket, filter)).filter(isModelRow);
const identities = usageIdentities(report, group, usageText(t));
return identities.of(rows).map((identity) => ({
key: identity.key,
@@ -1025,20 +1034,23 @@ export const UsageTab: React.FC<{
const allRows = filteredRows(report, { sourceIds: [], modelKeys: [] });
// A Source that metered nothing in this window still offers itself.
const sourceOptions: FilterOption[] = usageIdentities(report, 'source', usageText(t))
- .of([...allRows, ...report.sources.map((source) => ({ ...emptyCounters(), source_id: source.source_id, model_id: '' }))])
+ .of([...allRows, ...[...report.sources, ...report.services].map((source) => ({ ...emptyCounters(), source_id: source.source_id, model_id: '' }))])
.map((identity) => ({ key: identity.key, label: identity.label }));
- const modelOptions: FilterOption[] = usageIdentities(report, 'model', usageText(t)).of(allRows).map((identity) => ({
+ const modelOptions: FilterOption[] = usageIdentities(report, 'model', usageText(t)).of(allRows.filter(isModelRow)).map((identity) => ({
key: identity.key,
label: identity.label,
detail: identity.unlisted ? t('settings.models.usage.removedModel') : undefined,
}));
const filter = resolveUsageFilter(report, selection);
const scopedRows = filteredRows(report, filter);
- const totals = aggregateCounters(scopedRows);
+ const unpriced = unpricedServices(report);
+ // Every figure counts model calls; only the cost also counts search requests.
+ const totals = aggregateCounters(scopedRows, unpriced);
const partialHistory = reportHasPartialHistory(report, filter);
const reportEmpty = usageIsEmpty(report);
const filteredEmpty = !reportEmpty && scopedRows.length === 0 && !partialHistory;
- const historyOnlyUnknown = partialHistory && scopedRows.length === 0;
+ const historyOnlyUnknown = partialHistory && !scopedRows.some(isModelRow);
+ const costOnlyUnknown = partialHistory && scopedRows.length === 0;
const pinnedBucket = pinnedKey === null
? null
: report.buckets.find((bucket) => bucket.key === pinnedKey) ?? null;
@@ -1048,9 +1060,27 @@ export const UsageTab: React.FC<{
// The removed aggregate closes the list whichever way it is sorted.
const sortedRows = [...rows].sort((left, right) => (Number(left.removed) - Number(right.removed))
|| (sortValue(right) - sortValue(left)) * (sortAscending ? -1 : 1));
- const tableTotal = aggregateCounters(
- (activePinnedKey === null ? report.buckets : report.buckets.filter((bucket) => bucket.key === activePinnedKey))
- .flatMap((bucket) => filterBucketRows(bucket, filter)),
+ const tableScope = (activePinnedKey === null ? report.buckets : report.buckets.filter((bucket) => bucket.key === activePinnedKey))
+ .flatMap((bucket) => filterBucketRows(bucket, filter));
+ const tableTotal = aggregateCounters(tableScope.filter(isModelRow));
+ const serviceRows = serviceUsageRows(report, filter, activePinnedKey, usageText(t));
+ const serviceTotal = aggregateServiceRows(tableScope.filter(isServiceRow), unpriced);
+ const reportHasServices = allRows.some(isServiceRow);
+ const serviceCost = (totals: ServiceTotals) => (usageHasNoPrice(totals)
+ ? noPriceText(report, t)
+ : formatCost(totals.api_cost_usd ?? 0, totals.api_cost_lower_bound, i18n.language));
+ const serviceReported = (totals: ServiceTotals) => (totals.reported_requests > 0
+ ? formatUsd(totals.reported_usd ?? 0, i18n.language)
+ : t('settings.models.usage.blank'));
+ const serviceBillable = (totals: ServiceTotals) => (
+ <>
+ {count(totals.billable_requests)}
+ {totals.uncertain_requests > 0 && (
+ <span className="model-hub-usage-row-detail">
+ {t('settings.models.usage.services.uncertain', { count: totals.uncertain_requests, requests: count(totals.uncertain_requests) })}
+ </span>
+ )}
+ </>
);
const metricText = (counters: UsageCounters, selectedMetric = metric) => {
const text = tokenText(counters, selectedMetric, selectedMetric === metric ? format : count, t('settings.models.usage.blank') as string);
@@ -1174,16 +1204,26 @@ export const UsageTab: React.FC<{
{priced && (
<StatCard
label={t('settings.models.usage.stats.cost')}
- value={historyOnlyUnknown || !usageIsPriced(totals)
+ value={costOnlyUnknown || !usageIsPriced(totals)
? t('settings.models.usage.blank')
: usageHasNoPrice(totals)
? noPriceText(report, t)
: formatCost(totals.api_cost_usd ?? 0, totals.api_cost_lower_bound, i18n.language)}
note={[
t('settings.models.usage.cost.notBilled'),
+ // The vendors' own figures sit beside the list valuation, never in it.
+ (totals.service_reported_usd ?? 0) > 0
+ ? t('settings.models.usage.cost.reported', { usd: formatUsd(totals.service_reported_usd ?? 0, i18n.language) })
+ : null,
(totals.excluded_tokens ?? 0) > 0 && !usageHasNoPrice(totals) && !report.pricing?.pending
? t('settings.models.usage.cost.excluded', { count: totals.excluded_tokens ?? 0, tokens: count(totals.excluded_tokens ?? 0) })
: null,
+ (totals.excluded_service_requests ?? 0) > 0 && !usageHasNoPrice(totals)
+ ? t('settings.models.usage.cost.excludedServices', {
+ count: totals.excluded_service_requests ?? 0,
+ requests: count(totals.excluded_service_requests ?? 0),
+ })
+ : null,
report.pricing?.price_table_date
? t('settings.models.usage.cost.tableDate', { date: report.pricing.price_table_date })
: report.pricing?.pending
@@ -1334,6 +1374,66 @@ export const UsageTab: React.FC<{
{t('settings.models.usage.table.accounting')}
</div>
</section>
+ {reportHasServices && (
+ <section className="model-hub-usage-card model-hub-usage-details" aria-labelledby="model-hub-usage-services-title">
+ <div className="model-hub-usage-card-header model-hub-usage-details-header">
+ <div>
+ <h3 id="model-hub-usage-services-title">{t('settings.models.usage.services.title')} <span>{serviceRows.length}</span></h3>
+ <p>{activePinnedKey === null
+ ? t('settings.models.usage.table.range')
+ : t('settings.models.usage.table.bucket', { bucket: formatBucketLabel(pinnedBucket!, i18n.language) })}</p>
+ </div>
+ </div>
+ <div className="model-hub-usage-table-scroll">
+ <table>
+ <thead>
+ <tr>
+ <th scope="col">{t('settings.models.usage.services.identity')}</th>
+ <th scope="col">{t('settings.models.usage.table.requests')}</th>
+ <th scope="col">{t('settings.models.usage.services.billable')}</th>
+ {priced && <th scope="col">{t('settings.models.usage.metric.cost')}</th>}
+ {priced && <th scope="col">{t('settings.models.usage.services.reported')}</th>}
+ </tr>
+ </thead>
+ <tbody>
+ {serviceRows.map((row) => (
+ <tr key={row.key} className={cn(row.removed && 'is-removed')}>
+ <th scope="row">
+ <span className="model-hub-usage-row-name">{row.label}</span>
+ <span className="model-hub-usage-row-detail">{row.removed ? t('settings.models.usage.removedSourcesHint') : row.service}</span>
+ </th>
+ <td>{count(row.totals.requests)}</td>
+ <td>{serviceBillable(row.totals)}</td>
+ {priced && <td className={cn('model-hub-usage-table-total', usageHasNoPrice(row.totals) && 'is-unpriced')}>{serviceCost(row.totals)}</td>}
+ {priced && <td>{serviceReported(row.totals)}</td>}
+ </tr>
+ ))}
+ {serviceRows.length === 0 && <tr><td colSpan={priced ? 5 : 3} className="model-hub-usage-table-empty">{t('settings.models.usage.table.empty')}</td></tr>}
+ </tbody>
+ {serviceRows.length > 0 && (
+ <tfoot>
+ <tr>
+ <th scope="row">{t('settings.models.usage.table.total')}</th>
+ <td>{count(serviceTotal.requests)}</td>
+ <td>{serviceBillable(serviceTotal)}</td>
+ {priced && <td>{serviceCost(serviceTotal)}</td>}
+ {priced && <td>{serviceReported(serviceTotal)}</td>}
+ </tr>
+ </tfoot>
+ )}
+ </table>
+ </div>
+ <div className="model-hub-usage-table-foot">
+ <CircleHelp aria-hidden className="size-3.5 shrink-0" />
+ {[
+ t('settings.models.usage.services.accounting'),
+ report.pricing?.service_price_date
+ ? t('settings.models.usage.services.priceDate', { date: report.pricing.service_price_date })
+ : null,
+ ].filter(Boolean).join(' ')}
+ </div>
+ </section>
+ )}
</>
)}
</div>
diff --git a/ui/src/components/settings/models/apiFailure.test.ts b/ui/src/components/settings/models/apiFailure.test.ts
index 06831842b..3f48174a3 100644
--- a/ui/src/components/settings/models/apiFailure.test.ts
+++ b/ui/src/components/settings/models/apiFailure.test.ts
@@ -33,7 +33,7 @@ afterEach(() => {
describe('apiFailure — whether the route named the failure', () => {
it('posts installation to the dedicated runtime route', async () => {
const runtime = {
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'sha', assets: [] },
status: { installed_version: null, verified: false, listening: null, health: 'installing', last_check: null },
} as const;
diff --git a/ui/src/components/settings/models/gatewayAdoption.test.ts b/ui/src/components/settings/models/gatewayAdoption.test.ts
index 47e56ac79..69527194b 100644
--- a/ui/src/components/settings/models/gatewayAdoption.test.ts
+++ b/ui/src/components/settings/models/gatewayAdoption.test.ts
@@ -14,7 +14,7 @@ const agent = (mode: AgentSupply['mode']): AgentSupply => ({
});
const runtime = (health: RuntimeDependency['status']['health']): RuntimeDependency => ({
- contract_version: 18,
+ contract_version: 19,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: health === 'not_installed' ? null : '1', verified: health !== 'not_installed', health },
});
diff --git a/ui/src/components/settings/models/routeProjectionReconciliation.test.ts b/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
index d98620456..ba9824d7c 100644
--- a/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
+++ b/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
@@ -24,7 +24,7 @@ const source: Source = {
};
const report: RouteReport = {
chain: {
- contract_version: 18,
+ contract_version: 19,
backend: "claude",
model_id: "模型/opus",
manual_override: null,
diff --git a/ui/src/components/settings/models/runtimeLifecycle.test.ts b/ui/src/components/settings/models/runtimeLifecycle.test.ts
index 0bbc553c3..f60cb08a8 100644
--- a/ui/src/components/settings/models/runtimeLifecycle.test.ts
+++ b/ui/src/components/settings/models/runtimeLifecycle.test.ts
@@ -11,7 +11,7 @@ const asset = (platform: 'darwin-arm64' | 'linux-amd64') => ({
});
const runtime = (resolution: 'resolved' | 'unresolved' | 'unsupported'): RuntimeDependency => ({
- contract_version: 18,
+ contract_version: 19,
host_platform: 'darwin-arm64',
manifest: resolution === 'unresolved'
? { name: 'cliproxyapi', resolution, assets: [] }
diff --git a/ui/src/components/settings/models/types.ts b/ui/src/components/settings/models/types.ts
index a4797c591..a722933a3 100644
--- a/ui/src/components/settings/models/types.ts
+++ b/ui/src/components/settings/models/types.ts
@@ -10,8 +10,8 @@
// and the PR records the server implementation and feature-flag activation
// edge. The client never synthesizes a fallback payload shape.
-export const CONTRACT_VERSION = 18 as const;
-export const PERSISTED_TURN_CONTRACT_VERSIONS = [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18] as const;
+export const CONTRACT_VERSION = 19 as const;
+export const PERSISTED_TURN_CONTRACT_VERSIONS = [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] as const;
export const AGENT_CHAIN_CONTRACT_VERSION = CONTRACT_VERSION;
export const PROBE_RESULT_CONTRACT_VERSION = CONTRACT_VERSION;
@@ -884,6 +884,63 @@ export type UsagePricing = {
/** No price table yet and a first fetch is running; re-read soon, and say
* prices are being fetched rather than that there are none. */
pending?: true;
+ /** When the oldest catalog price that valued `services` was verified; absent
+ * when no service was valued. */
+ service_price_date?: string;
+};
+
+/** What a model total adds for search services (`web-search-services.md` §4.3):
+ * `totals` and `days` keep counting model calls, and only their `api_cost_usd`
+ * includes the services' list valuation. Present exactly when the report is priced. */
+export type ServiceCostTotals = {
+ /** The vendors' own reported search costs, beside `api_cost_usd` and never added to it. */
+ service_reported_usd: number;
+ /** Billable search requests the current catalog no longer prices, left out of `api_cost_usd`. */
+ excluded_service_requests: number;
+};
+
+export type UsageTotals = UsageCounters & Partial<ServiceCostTotals>;
+
+/** Sent search-service requests. A request reaches no model, so no model
+ * counter ever includes one. */
+export type ServiceCounters = {
+ requests: number;
+ /** The subset the catalog's billing rule charges, each valued at its list price. */
+ billable_requests: number;
+ /** The subset whose billing is unknown: never billable, and a floor on the cost. */
+ uncertain_requests: number;
+ /** The subset of `billable_requests` the vendor priced itself. */
+ reported_requests: number;
+} & Partial<ServicePricedUsage>;
+
+/** Present exactly when the report is priced. */
+export type ServicePricedUsage = {
+ /** `billable_requests` at the current catalog's list price. */
+ api_cost_usd: number;
+ /** The vendors' figures for `reported_requests`, never added to `api_cost_usd`. */
+ reported_usd: number;
+ /** The valuation is only a floor: billing unknown, a repaired row, or a price
+ * the catalog no longer has. */
+ api_cost_lower_bound: boolean;
+};
+
+/** One Source's search service over the window. A tool-only Source appears
+ * only here, never in `sources`. */
+export type ServiceUsage = ServiceCounters & {
+ source_id: string;
+ /** The catalog's service ID, such as `tavily/search`. */
+ service_id: string;
+ /** Joined from current Source config; null exactly when config no longer
+ * holds the Source, which then folds into the removed-Sources identity. */
+ label: string | null;
+ /** The current catalog's name for the service; null once the catalog no
+ * longer lists it, and views show `service_id`. */
+ service_label: string | null;
+ last_metered_at: string | null;
+ /** False when the current catalog no longer prices the service, so its
+ * billable requests are left out of `api_cost_usd`. Present exactly when
+ * the report is priced. */
+ priced?: boolean;
};
export type UsageByModel = UsageCounters & {
@@ -912,7 +969,7 @@ export type UsageBySource = UsageCounters & {
models: UsageByModel[];
};
-export type UsageByDay = UsageCounters & { day: string };
+export type UsageByDay = UsageTotals & { day: string };
export type UsageSummary = {
/** The window the server actually served, after clamping to retention. Views
@@ -922,9 +979,11 @@ export type UsageSummary = {
from_day: string;
/** Last local day of the window, which is the host's today. */
to_day: string;
- totals: UsageCounters;
+ totals: UsageTotals;
/** One entry per Source with at least one metered turn, busiest first. */
sources: UsageBySource[];
+ /** One entry per Source and search service with a sent request, busiest first. */
+ services: ServiceUsage[];
/** One entry per local day carrying a metered turn, oldest first — a trend
* series, so a day with no turn is ABSENT rather than reported as zero. */
days: UsageByDay[];
@@ -934,17 +993,28 @@ export type UsageSummary = {
export type UsageWindowKey = '24h' | '7d' | '30d' | '60d';
+/** A model row, the released shape, which never carries `kind`. */
export type UsageBucketRow = UsageCounters & {
+ kind?: never;
source_id: string;
model_id: string;
};
+/** A search-service row: its own counters, never dressed as a model. */
+export type UsageServiceBucketRow = ServiceCounters & {
+ kind: 'service';
+ source_id: string;
+ service_id: string;
+};
+
+export type UsageBucketEntry = UsageBucketRow | UsageServiceBucketRow;
+
export type UsageBucket = {
key: string;
start_at: string;
end_at: string;
history_complete: boolean;
- rows: UsageBucketRow[];
+ rows: UsageBucketEntry[];
};
/** The modern temporal report consumed by the Model Hub analytics surface. */
@@ -1039,7 +1109,7 @@ export type HostedToolName = (typeof HOSTED_TOOL_NAMES)[number];
export type HostedSearchToolName = Exclude<HostedToolName, 'image_generate'>;
/** How a call ran: natively in the model's request, through a search executor, or on an image endpoint. */
-export type HostedExecutionMode = 'native' | 'executor' | 'direct';
+export type HostedExecutionMode = 'native' | 'executor' | 'service' | 'direct';
/** A positive record: a real response ran the tool on this (Source, model). Display only. */
export type HostedSuccess = { source_id: string; model_id: string; mode: HostedExecutionMode; at: string };
diff --git a/ui/src/components/settings/models/usageCsv.ts b/ui/src/components/settings/models/usageCsv.ts
index d13175bf0..4c9bbb212 100644
--- a/ui/src/components/settings/models/usageCsv.ts
+++ b/ui/src/components/settings/models/usageCsv.ts
@@ -2,6 +2,7 @@ import type { UsageBucketRow, UsageReport } from './types';
import {
filterBucketRows,
emptyCounters,
+ isModelRow,
modelLabel,
usageNonCachedInput,
usageTokensAreKnown,
@@ -42,15 +43,16 @@ export function buildUsageCsv(
headers: UsageCsvHeaders,
unknownModel: string,
): string {
- // The export keeps every row under the IDs it was metered under; a label is
- // what config names that ID, and a Source config let go reads as its ID.
+ // The export keeps every model row under the IDs it was metered under; a label
+ // is what config names that ID, and a Source config let go reads as its ID.
+ // Search requests are no model's calls or tokens, so they are not exported.
const sourceLabel = (sourceId: string) => report.sources
.find((source) => source.source_id === sourceId)?.label?.trim() || sourceId;
const buckets = pinnedKey === null
? report.buckets
: report.buckets.filter((bucket) => bucket.key === pinnedKey);
const lines = buckets.flatMap((bucket) => {
- const rows = filterBucketRows(bucket, filter);
+ const rows = filterBucketRows(bucket, filter).filter(isModelRow);
const exportRows: Array<UsageBucketRow | null> = rows.length > 0 ? rows : [null];
return exportRows.map((row) => {
const counters = row ?? (bucket.history_complete ? emptyCounters() : null);
diff --git a/ui/src/components/settings/models/usageProjection.test.ts b/ui/src/components/settings/models/usageProjection.test.ts
index 97c20ba07..1c63974c2 100644
--- a/ui/src/components/settings/models/usageProjection.test.ts
+++ b/ui/src/components/settings/models/usageProjection.test.ts
@@ -1,6 +1,6 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { UsageBucket, UsageBucketRow, UsageCounters, UsageReport } from './types';
+import type { ServiceUsage, UsageBucket, UsageBucketEntry, UsageBucketRow, UsageCounters, UsageReport, UsageServiceBucketRow } from './types';
import {
aggregateCounters,
filteredRows,
@@ -8,22 +8,27 @@ import {
formatBucketAxisLabel,
formatBucketHeading,
formatBucketRange,
+ isModelRow,
pairKey,
REMOVED_SOURCES_KEY,
reportHasPartialHistory,
reportIsPriced,
resolveUsageFilter,
seriesFor,
+ serviceMonthUsage,
+ serviceUsageRows,
+ usageHasNoPrice,
usageIdentities,
usageIsEmpty,
usageIsPriced,
usageMetricValue,
usageNonCachedInput,
usageTotalTokens,
+ type UsageFilter,
} from './usageProjection';
-const TEXT = { unknownModel: 'Unknown model', removedSources: 'Removed providers' };
-const TEXT_ZH = { unknownModel: '未知模型', removedSources: '已移除的供应商' };
+const TEXT = { unknownModel: 'Unknown model', removedSources: 'Removed providers', searchServices: 'Search services' };
+const TEXT_ZH = { unknownModel: '未知模型', removedSources: '已移除的供应商', searchServices: '搜索服务' };
const NO_FILTER = { sourceIds: [], modelKeys: [] };
const counters = (over: Partial<UsageCounters> = {}): UsageCounters => ({
@@ -47,6 +52,7 @@ const reportWith = (buckets: UsageBucket[]): UsageReport => ({
...counters(),
models: [{ model_id: 'model-a', label: 'Model', ...counters() }],
}],
+ services: [],
days: [],
window_key: '24h',
granularity: 'hour',
@@ -62,7 +68,7 @@ const row = (over: Partial<UsageBucketRow> = {}): UsageBucketRow => ({
...over,
});
-const bucket = (key: string, rows: UsageBucketRow[], history_complete = true): UsageBucket => ({
+const bucket = (key: string, rows: UsageBucketEntry[], history_complete = true): UsageBucket => ({
key,
start_at: `2026-09-24T${key}:00:00+08:00`,
end_at: `2026-09-24T${String(Number(key) + 1).padStart(2, '0')}:00:00+08:00`,
@@ -159,7 +165,7 @@ describe('usageProjection', () => {
{ sourceIds: [], modelKeys: [REMOVED_SOURCES_KEY] },
]) {
const rows = filteredRows(value, resolveUsageFilter(value, selection));
- expect(rows.map((item) => item.model_id).sort()).toEqual(['deepseek-v3', 'glm-5.3', 'kimi-k2']);
+ expect(rows.map((item) => (isModelRow(item) ? item.model_id : item.service_id)).sort()).toEqual(['deepseek-v3', 'glm-5.3', 'kimi-k2']);
}
const live = filteredRows(value, resolveUsageFilter(value, { sourceIds: ['source-a'], modelKeys: [REMOVED_SOURCES_KEY] }));
expect(live).toEqual([]);
@@ -275,3 +281,154 @@ describe('usageProjection', () => {
expect(reportIsPriced({ ...reportWith([]), pricing: { currency: 'USD', price_table_date: null } })).toBe(true);
});
});
+
+// A search request (`web-search-services.md` §4.3) shares a bucket with model
+// calls but reaches no model: it counts toward cost alone.
+describe('search-service usage', () => {
+ afterEach(() => { vi.useRealTimers(); });
+
+ const search = (over: Partial<UsageServiceBucketRow> = {}): UsageServiceBucketRow => ({
+ kind: 'service',
+ source_id: 'src_exa',
+ service_id: 'exa/search',
+ requests: 3,
+ billable_requests: 2,
+ uncertain_requests: 1,
+ reported_requests: 2,
+ reported_usd: 0.0135,
+ api_cost_usd: 0.014,
+ api_cost_lower_bound: true,
+ ...over,
+ });
+ const listing = (entry: UsageServiceBucketRow, over: Partial<ServiceUsage>): ServiceUsage => ({
+ source_id: entry.source_id,
+ service_id: entry.service_id,
+ label: null,
+ service_label: null,
+ last_metered_at: null,
+ requests: entry.requests,
+ billable_requests: entry.billable_requests,
+ uncertain_requests: entry.uncertain_requests,
+ reported_requests: entry.reported_requests,
+ priced: true,
+ ...over,
+ });
+ const exa = search();
+ const tavily = search({
+ source_id: 'src_tavily', service_id: 'tavily/search', requests: 1, billable_requests: 1, uncertain_requests: 0,
+ reported_requests: 0, reported_usd: 0, api_cost_usd: 0.008, api_cost_lower_bound: false,
+ });
+ // A Source config let go, whose service a later catalog no longer prices.
+ const retired = search({
+ source_id: 'src_gone', service_id: 'retired/search', requests: 1, billable_requests: 1, uncertain_requests: 0,
+ reported_requests: 0, reported_usd: 0, api_cost_usd: 0, api_cost_lower_bound: true,
+ });
+ const withServices = (): UsageReport => ({
+ ...reportWith([
+ bucket('00', [row({ api_cost_usd: 0.5, excluded_tokens: 0, api_cost_lower_bound: false }), exa, tavily]),
+ bucket('01', [retired]),
+ ]),
+ services: [
+ listing(exa, { label: 'Exa key' }),
+ listing(tavily, { label: 'Tavily', service_label: 'Tavily' }),
+ listing(retired, { priced: false }),
+ ],
+ pricing: { currency: 'USD', price_table_date: '2026-09-23', service_price_date: '2026-09-20' },
+ });
+ const values = (value: UsageReport, filter: UsageFilter, metric: 'cost' | 'requests') =>
+ seriesFor(value, filter, 'total', metric, TEXT)[0]!.values.map((item) => (item === null ? null : Number(item.toFixed(6))));
+
+ it('MH-USAGE-036: adds search cost under the Source filter, never under a model filter, and no call or token', () => {
+ const value = withServices();
+ const cost = seriesFor(value, NO_FILTER, 'total', 'cost', TEXT)[0]!;
+ expect(values(value, NO_FILTER, 'cost')).toEqual([0.522, 0]);
+ // A retired service's request is unpriced, never $0.
+ expect([cost.floors, cost.unpriced]).toEqual([[true, true], [false, true]]);
+ expect(values(value, NO_FILTER, 'requests')).toEqual([2, 0]);
+ expect(values(value, { sourceIds: ['src_exa'], modelKeys: [] }, 'cost')).toEqual([0.014, 0]);
+ expect(values(value, { sourceIds: ['src_exa'], modelKeys: [] }, 'requests')).toEqual([0, 0]);
+ const model = { sourceIds: [], modelKeys: [pairKey('source-a', 'model-a')] };
+ expect(filteredRows(value, model).every(isModelRow)).toBe(true);
+ expect(values(value, model, 'cost')).toEqual([0.5, 0]);
+ // Grouped, the services keep the stack equal to the total; only cost shows them.
+ const labels = (group: 'model' | 'source', metric: 'cost' | 'tokens') => seriesFor(value, NO_FILTER, group, metric, TEXT).map((item) => item.label);
+ expect(labels('model', 'cost')).toEqual(['Supplier · Model', 'Search services', 'Removed providers']);
+ expect(labels('source', 'cost')).toEqual(['Supplier', 'Exa key', 'Tavily', 'Removed providers']);
+ expect(labels('source', 'tokens')).toEqual(['Supplier']);
+ // A tool-only Source is a Source to filter by, never a model.
+ expect(foldUsageSelection(value, { sourceIds: ['src_exa'], modelKeys: [pairKey('src_exa', 'exa/search')] }))
+ .toEqual({ sourceIds: ['src_exa'], modelKeys: [] });
+ });
+
+ it('MH-USAGE-036: reads service-only usage as usage, with no call or token in it', () => {
+ const value = { ...reportWith([bucket('00', [exa])]), services: [listing(exa, { label: 'Exa key' })] };
+ expect(usageIsEmpty(value)).toBe(false);
+ expect(values(value, NO_FILTER, 'requests')).toEqual([0]);
+ expect(seriesFor(value, NO_FILTER, 'total', 'tokens', TEXT)[0]!.values).toEqual([0]);
+ });
+
+ it('MH-USAGE-036: tables each live service by its catalog name and folds removed Sources, keeping their counts', () => {
+ const value = withServices();
+ const table = (filter: UsageFilter, pinned: string | null = null) => serviceUsageRows(value, filter, pinned, TEXT)
+ .map(({ label, service, removed, totals }) => [label, service, removed, totals.requests, totals.billable_requests,
+ totals.uncertain_requests, totals.api_cost_usd, totals.reported_usd, usageHasNoPrice(totals)]);
+ expect(table(NO_FILTER)).toEqual([
+ // No catalog name left for the service: its ID.
+ ['Exa key', 'exa/search', false, 3, 2, 1, 0.014, 0.0135, false],
+ ['Tavily', 'Tavily', false, 1, 1, 0, 0.008, 0, false],
+ ['Removed providers', '', true, 1, 1, 0, 0, 0, true],
+ ]);
+ expect(table(NO_FILTER, '01').map(([label]) => label)).toEqual(['Removed providers']);
+ expect(table({ sourceIds: [], modelKeys: [pairKey('source-a', 'model-a')] })).toEqual([]);
+ expect(aggregateCounters(filteredRows(value, NO_FILTER).filter((entry) => !isModelRow(entry))).requests).toBe(0);
+ });
+
+ describe('this month on a Source detail', () => {
+ const DAY = 24 * 60 * 60 * 1000;
+ // A 60-day daily report ending on the host's local today, `to_day`.
+ const daily = (toDay: string, rows: Partial<Record<string, UsageBucketEntry[]>>, incomplete: readonly string[] = []): UsageReport => {
+ const end = Date.parse(`${toDay}T00:00:00Z`);
+ const keys = Array.from({ length: 60 }, (_, index) => new Date(end - (59 - index) * DAY).toISOString().slice(0, 10));
+ return {
+ ...reportWith(keys.map((key) => ({
+ key, start_at: `${key}T00:00:00-07:00`, end_at: `${key}T23:59:59-07:00`, history_complete: !incomplete.includes(key), rows: rows[key] ?? [],
+ }))),
+ window_key: '60d', granularity: 'day', window_days: 60, from_day: keys[0]!, to_day: toDay,
+ pricing: { currency: 'USD', price_table_date: '2026-09-23' },
+ };
+ };
+ const one = (over: Partial<UsageServiceBucketRow> = {}) => search({ requests: 1, billable_requests: 1, uncertain_requests: 0, reported_requests: 0, reported_usd: 0, api_cost_usd: 0.007, api_cost_lower_bound: false, ...over });
+
+ it.each([
+ {
+ name: 'a 31-day month, from its first day to the host\'s today',
+ toDay: '2026-10-31',
+ rows: { '2026-09-30': [one()], '2026-10-01': [one({ requests: 2, billable_requests: 2, api_cost_usd: 0.014 })], '2026-10-15': [one({ source_id: 'src_other' })], '2026-10-31': [one()] },
+ incomplete: ['2026-09-30'],
+ expected: { month: '2026-10', requests: 3, cost: 0.021, partial: false },
+ },
+ {
+ // The browser's clock is still on October; the host's day is what counts.
+ name: 'the host\'s new month, ahead of the browser\'s',
+ toDay: '2026-11-01',
+ rows: { '2026-10-31': [one({ requests: 5, billable_requests: 5 })], '2026-11-01': [one()] },
+ incomplete: [],
+ expected: { month: '2026-11', requests: 1, cost: 0.007, partial: false },
+ },
+ {
+ name: 'a month with a day missing its history',
+ toDay: '2026-10-20',
+ rows: { '2026-10-02': [one()] },
+ incomplete: ['2026-10-03'],
+ expected: { month: '2026-10', requests: 1, cost: 0.007, partial: true },
+ },
+ ])('MH-USAGE-038: counts $name', ({ toDay, rows, incomplete, expected }) => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date('2026-10-31T12:00:00-07:00'));
+ const month = serviceMonthUsage(daily(toDay, rows, incomplete), 'src_exa');
+ expect({ month: month.month, requests: month.totals.requests, cost: Number(month.totals.api_cost_usd?.toFixed(6)), partial: month.partial })
+ .toEqual(expected);
+ expect(month.priced).toBe(true);
+ });
+ });
+});
diff --git a/ui/src/components/settings/models/usageProjection.ts b/ui/src/components/settings/models/usageProjection.ts
index 2c73fee06..96dc4090f 100644
--- a/ui/src/components/settings/models/usageProjection.ts
+++ b/ui/src/components/settings/models/usageProjection.ts
@@ -1,9 +1,13 @@
import type {
+ ServiceCounters,
UsageBucket,
+ UsageBucketEntry,
UsageBucketRow,
UsageCounters,
UsageReport,
+ UsageServiceBucketRow,
UsageSummary,
+ UsageTotals,
UsageWindowKey,
} from './types';
@@ -43,8 +47,54 @@ export const emptyCounters = (): UsageCounters => ({
output_tokens: 0,
});
-export function aggregateCounters(rows: readonly UsageCounters[]): UsageCounters {
- const total = rows.reduce<UsageCounters>((sum, row) => ({
+/** Model counters, or a search-service row: what a usage total can be summed from. */
+type CountedRow = UsageCounters | UsageServiceBucketRow;
+
+export const isServiceRow = (row: CountedRow): row is UsageServiceBucketRow =>
+ (row as { kind?: unknown }).kind === 'service';
+
+export const isModelRow = (row: UsageBucketEntry): row is UsageBucketRow => !isServiceRow(row);
+
+/** A search service's totals, and its billable requests the current catalog no longer prices. */
+export type ServiceTotals = ServiceCounters & { excluded_service_requests: number };
+
+/**
+ * The (Source, service) pairs whose service the current catalog no longer
+ * prices. A bucket row cannot say so; `services` does, for the whole window.
+ */
+export const unpricedServices = (report: UsageSummary): ReadonlySet<string> => new Set(report.services
+ .filter((service) => service.priced === false)
+ .map((service) => pairKey(service.source_id, service.service_id)));
+
+export function aggregateServiceRows(
+ rows: readonly UsageServiceBucketRow[],
+ unpriced: ReadonlySet<string>,
+): ServiceTotals {
+ const sum = (value: (row: UsageServiceBucketRow) => number) => rows.reduce((total, row) => total + value(row), 0);
+ const total: ServiceTotals = {
+ requests: sum((row) => row.requests),
+ billable_requests: sum((row) => row.billable_requests),
+ uncertain_requests: sum((row) => row.uncertain_requests),
+ reported_requests: sum((row) => row.reported_requests),
+ excluded_service_requests: sum((row) => (unpriced.has(pairKey(row.source_id, row.service_id)) ? row.billable_requests : 0)),
+ };
+ if (rows.length > 0 && rows.every(usageIsPriced)) {
+ total.api_cost_usd = sum((row) => row.api_cost_usd ?? 0);
+ total.reported_usd = sum((row) => row.reported_usd ?? 0);
+ total.api_cost_lower_bound = rows.some((row) => row.api_cost_lower_bound === true);
+ }
+ return total;
+}
+
+/**
+ * A search request is not a model call, so a service row adds no request or
+ * token to the sum, only its cost. The billable requests of a service the
+ * catalog no longer prices (`unpricedServices`) are left out of that cost, as
+ * an unpriced model's tokens are.
+ */
+export function aggregateCounters(rows: readonly CountedRow[], unpriced: ReadonlySet<string> = new Set()): UsageTotals {
+ const models = rows.filter((row): row is UsageCounters => !isServiceRow(row));
+ const total = models.reduce<UsageTotals>((sum, row) => ({
requests: sum.requests + row.requests,
token_reports: sum.token_reports + row.token_reports,
input_tokens: sum.input_tokens + row.input_tokens,
@@ -53,19 +103,24 @@ export function aggregateCounters(rows: readonly UsageCounters[]): UsageCounters
}), emptyCounters());
// A priced row carries its cost; the sum is priced only when every row is.
if (rows.length > 0 && rows.every(usageIsPriced)) {
+ const services = aggregateServiceRows(rows.filter(isServiceRow), unpriced);
total.api_cost_usd = rows.reduce((sum, row) => sum + (row.api_cost_usd ?? 0), 0);
- total.excluded_tokens = rows.reduce((sum, row) => sum + (row.excluded_tokens ?? 0), 0);
+ total.excluded_tokens = models.reduce((sum, row) => sum + (row.excluded_tokens ?? 0), 0);
total.api_cost_lower_bound = rows.some((row) => row.api_cost_lower_bound === true);
+ total.service_reported_usd = services.reported_usd ?? 0;
+ total.excluded_service_requests = services.excluded_service_requests;
}
return total;
}
/** Whether the server priced these counters at API prices. */
-export const usageIsPriced = (counters: UsageCounters): boolean => typeof counters.api_cost_usd === 'number';
+export const usageIsPriced = (counters: { api_cost_usd?: number }): boolean => typeof counters.api_cost_usd === 'number';
-/** Every priced token of these counters belongs to a model with no known price. */
-export const usageHasNoPrice = (counters: UsageCounters): boolean =>
- usageIsPriced(counters) && (counters.excluded_tokens ?? 0) > 0 && (counters.api_cost_usd ?? 0) === 0;
+/** Everything these counters would price is left out: models and services with no known price. */
+export const usageHasNoPrice = (
+ counters: { api_cost_usd?: number; excluded_tokens?: number; excluded_service_requests?: number },
+): boolean => usageIsPriced(counters) && (counters.api_cost_usd ?? 0) === 0
+ && ((counters.excluded_tokens ?? 0) > 0 || (counters.excluded_service_requests ?? 0) > 0);
/** Whether the report carries API-price value at all: a server that predates it never does. */
export const reportIsPriced = (report: UsageSummary): boolean => report.pricing !== undefined;
@@ -215,6 +270,9 @@ export function formatBucketHeading(bucket: UsageBucket, locale: string): { rang
*/
export const REMOVED_SOURCES_KEY = `${PAIR_SEPARATOR}removed`;
+/** Grouped by model, every live Source's search services as one identity: none of them is a model. */
+export const SEARCH_SERVICES_KEY = `${PAIR_SEPARATOR}services`;
+
/**
* The longest ledger key, in code points as the ledger counts them, that is
* still the identifier itself; a longer one is a head plus a digest.
@@ -224,6 +282,7 @@ const LEDGER_VERBATIM_MAX_LENGTH = 200;
export type UsageText = {
unknownModel: string;
removedSources: string;
+ searchServices: string;
};
export type UsageIdentity = {
@@ -238,19 +297,20 @@ export type UsageIdentity = {
};
export type UsageIdentities = {
- keyOf: (row: UsageBucketRow) => string;
+ keyOf: (row: UsageBucketEntry) => string;
get: (key: string) => UsageIdentity;
/** These rows' identities in first-metered order, the removed aggregate last. */
- of: (rows: readonly UsageBucketRow[]) => UsageIdentity[];
+ of: (rows: readonly UsageBucketEntry[]) => UsageIdentity[];
};
-const allRows = (report: UsageReport): UsageBucketRow[] => report.buckets.flatMap((bucket) => bucket.rows);
+const allRows = (report: UsageReport): UsageBucketEntry[] => report.buckets.flatMap((bucket) => bucket.rows);
/**
* The Sources config still holds, by ID. A configured Source always carries its
- * name, so the report leaves the label null exactly when config let it go.
+ * name, so the report leaves the label null exactly when config let it go. A
+ * tool-only Source is named only by its search usage.
*/
-const liveSources = (report: UsageReport) => new Map(report.sources
+const liveSources = (report: UsageReport) => new Map([...report.sources, ...report.services]
.filter((source) => source.label != null)
.map((source) => [source.source_id, source.label!.trim()] as const));
@@ -302,17 +362,17 @@ function distinctLabels(entries: ReadonlyArray<readonly [string, string]>): Map<
* under one, keeps its own identity; every row of a Source config no longer
* holds folds into one removed aggregate, so its counters still add up while
* no Source ID reaches the screen. Labels come from the whole report, so a
- * filter never renames what stays on screen.
+ * filter never renames what stays on screen. A search-service row belongs to
+ * its Source, and grouped by model, to the one search-services identity.
*/
export function usageIdentities(report: UsageReport, group: 'model' | 'source', text: UsageText): UsageIdentities {
const live = liveSources(report);
const removed = (sourceId: string) => !live.has(sourceId);
- const keyOf = (row: UsageBucketRow) => (removed(row.source_id)
+ const keyOf = (row: UsageBucketEntry) => (removed(row.source_id)
? REMOVED_SOURCES_KEY
- : group === 'source' ? row.source_id : pairKey(row.source_id, row.model_id));
+ : group === 'source' ? row.source_id : isServiceRow(row) ? SEARCH_SERVICES_KEY : pairKey(row.source_id, row.model_id));
const rows = allRows(report);
- const hasRemoved = report.sources.some((source) => removed(source.source_id))
- || rows.some((row) => removed(row.source_id));
+ const hasRemoved = [...report.sources, ...report.services, ...rows].some((entry) => removed(entry.source_id));
const removedEntry = hasRemoved ? [[REMOVED_SOURCES_KEY, text.removedSources] as const] : [];
// The aggregate keeps the product's own name; live Sources tie-break by ID.
const sourceLabels = distinctLabels([...removedEntry, ...[...live].sort(byKey)]);
@@ -338,6 +398,7 @@ export function usageIdentities(report: UsageReport, group: 'model' | 'source',
}
} else {
const pairs = new Map(rows
+ .filter(isModelRow)
.filter((row) => !removed(row.source_id))
.map((row) => [pairKey(row.source_id, row.model_id), row] as const));
const models = new Map([...pairs].map(([key, row]) => [key, {
@@ -361,6 +422,15 @@ export function usageIdentities(report: UsageReport, group: 'model' | 'source',
unlisted: model.unlisted,
});
}
+ if (rows.some((row) => isServiceRow(row) && !removed(row.source_id))) {
+ identities.set(SEARCH_SERVICES_KEY, {
+ key: SEARCH_SERVICES_KEY,
+ label: text.searchServices,
+ sourceLabel: '',
+ removed: false,
+ unlisted: false,
+ });
+ }
}
const get = (key: string) => identities.get(key)!;
return {
@@ -386,12 +456,12 @@ export function usageIdentities(report: UsageReport, group: 'model' | 'source',
export function foldUsageSelection(report: UsageReport, selection: UsageFilter): UsageFilter {
const live = liveSources(report);
const rows = allRows(report);
- const known = new Set([...report.sources.map((source) => source.source_id), ...rows.map((row) => row.source_id)]);
+ const known = new Set([...report.sources, ...report.services, ...rows].map((entry) => entry.source_id));
const fold = (sourceId: string, key: string) => (live.has(sourceId) ? key : REMOVED_SOURCES_KEY);
- // What each filter lists: every Source the report names, and every pair it metered.
+ // What each filter lists: every Source the report names, and every model pair it metered.
const offered = {
sourceIds: new Set([...known].map((sourceId) => fold(sourceId, sourceId))),
- modelKeys: new Set(rows.map((row) => fold(row.source_id, pairKey(row.source_id, row.model_id)))),
+ modelKeys: new Set(rows.filter(isModelRow).map((row) => fold(row.source_id, pairKey(row.source_id, row.model_id)))),
};
const reconcile = (keys: readonly string[], options: ReadonlySet<string>, sourceOf: (key: string) => string) => [
...new Set(keys.map((key) => (known.has(sourceOf(key)) ? fold(sourceOf(key), key) : key))),
@@ -424,28 +494,35 @@ export function resolveUsageFilter(report: UsageReport, picked: UsageFilter): Us
)))];
return {
sourceIds: expand(selection.sourceIds, removedRows.map((row) => row.source_id)),
- modelKeys: expand(selection.modelKeys, removedRows.map((row) => pairKey(row.source_id, row.model_id))),
+ modelKeys: expand(selection.modelKeys, removedRows.filter(isModelRow).map((row) => pairKey(row.source_id, row.model_id))),
};
}
-export function filterBucketRows(bucket: UsageBucket, filter: UsageFilter): UsageBucketRow[] {
+/** A search request is no model's, so a model filter leaves out every service row; a Source filter keeps its own. */
+export function filterBucketRows(bucket: UsageBucket, filter: UsageFilter): UsageBucketEntry[] {
return bucket.rows.filter((row) => (
(filter.sourceIds.length === 0 || filter.sourceIds.includes(row.source_id))
- && (filter.modelKeys.length === 0 || filter.modelKeys.includes(pairKey(row.source_id, row.model_id)))
+ && (filter.modelKeys.length === 0 || (isModelRow(row) && filter.modelKeys.includes(pairKey(row.source_id, row.model_id))))
));
}
-export function filteredRows(report: UsageReport, filter: UsageFilter): UsageBucketRow[] {
+export function filteredRows(report: UsageReport, filter: UsageFilter): UsageBucketEntry[] {
return report.buckets.flatMap((bucket) => filterBucketRows(bucket, filter));
}
+/** The rows a metric counts: a service row has a cost, but no call or token. */
+export const metricRows = (rows: readonly UsageBucketEntry[], metric: UsageMetric): UsageBucketEntry[] => (
+ metric === 'cost' ? [...rows] : rows.filter(isModelRow)
+);
+
const typeSeries = (
- rows: UsageBucketRow[],
+ rows: UsageBucketEntry[],
metric: UsageMetric,
historyComplete: boolean,
+ unpriced: ReadonlySet<string>,
): Array<[string, number | null]> => {
if (metric === 'cost') {
- return [['cost', !historyComplete && rows.length === 0 ? null : usageMetricValue(aggregateCounters(rows), 'cost')]];
+ return [['cost', !historyComplete && rows.length === 0 ? null : usageMetricValue(aggregateCounters(rows, unpriced), 'cost')]];
}
if (!historyComplete && rows.length === 0) {
if (metric === 'requests') return [['requests', null]];
@@ -474,22 +551,23 @@ const typeSeries = (
};
/** Whether these rows' cost is only a floor, as the server marked it. */
-export const costIsFloor = (rows: readonly UsageCounters[], metric: UsageMetric): boolean => (
+export const costIsFloor = (rows: readonly CountedRow[], metric: UsageMetric): boolean => (
metric === 'cost' && aggregateCounters(rows).api_cost_lower_bound === true
);
/** Whether these rows' cost has nothing priced in it, as opposed to a floor of some priced part. */
-export const costIsUnpriced = (rows: readonly UsageCounters[], metric: UsageMetric): boolean => (
- metric === 'cost' && usageHasNoPrice(aggregateCounters(rows))
+export const costIsUnpriced = (rows: readonly CountedRow[], metric: UsageMetric, unpriced: ReadonlySet<string>): boolean => (
+ metric === 'cost' && usageHasNoPrice(aggregateCounters(rows, unpriced))
);
const bucketMetricValue = (
bucket: UsageBucket,
- rows: UsageBucketRow[],
+ rows: UsageBucketEntry[],
metric: UsageMetric,
+ unpriced: ReadonlySet<string>,
): number | null => {
if (!bucket.history_complete && rows.length === 0) return null;
- return usageMetricValue(aggregateCounters(rows), metric);
+ return usageMetricValue(aggregateCounters(rows, unpriced), metric);
};
export function seriesFor(
@@ -499,11 +577,12 @@ export function seriesFor(
metric: UsageMetric,
text: UsageText,
): UsageSeries[] {
- const rows = filteredRows(report, filter);
+ const inScope = (bucket: UsageBucket) => metricRows(filterBucketRows(bucket, filter), metric);
+ const unpricedKeys = unpricedServices(report);
if (group === 'type') {
const valuesByKey = new Map<string, Array<number | null>>();
for (const bucket of report.buckets) {
- for (const [key, value] of typeSeries(filterBucketRows(bucket, filter), metric, bucket.history_complete)) {
+ for (const [key, value] of typeSeries(inScope(bucket), metric, bucket.history_complete, unpricedKeys)) {
valuesByKey.set(key, [...(valuesByKey.get(key) ?? []), value]);
}
}
@@ -514,8 +593,8 @@ export function seriesFor(
requests: 'Requests',
cost: 'API price',
};
- const floors = report.buckets.map((bucket) => costIsFloor(filterBucketRows(bucket, filter), metric));
- const unpriced = report.buckets.map((bucket) => costIsUnpriced(filterBucketRows(bucket, filter), metric));
+ const floors = report.buckets.map((bucket) => costIsFloor(inScope(bucket), metric));
+ const unpriced = report.buckets.map((bucket) => costIsUnpriced(inScope(bucket), metric, unpricedKeys));
return [...valuesByKey.entries()].map(([key, values], index) => ({
key,
label: labels[key],
@@ -531,28 +610,23 @@ export function seriesFor(
key: 'total',
label: metric,
colorIndex: 0,
- values: report.buckets.map((bucket) => bucketMetricValue(
- bucket,
- filterBucketRows(bucket, filter),
- metric,
- )),
- floors: report.buckets.map((bucket) => costIsFloor(filterBucketRows(bucket, filter), metric)),
- unpriced: report.buckets.map((bucket) => costIsUnpriced(filterBucketRows(bucket, filter), metric)),
+ values: report.buckets.map((bucket) => bucketMetricValue(bucket, inScope(bucket), metric, unpricedKeys)),
+ floors: report.buckets.map((bucket) => costIsFloor(inScope(bucket), metric)),
+ unpriced: report.buckets.map((bucket) => costIsUnpriced(inScope(bucket), metric, unpricedKeys)),
}];
}
const identities = usageIdentities(report, group, text);
- return identities.of(rows).map((identity, index) => {
- const rowsOf = (bucket: UsageBucket) => filterBucketRows(bucket, filter)
- .filter((row) => identities.keyOf(row) === identity.key);
+ return identities.of(report.buckets.flatMap(inScope)).map((identity, index) => {
+ const rowsOf = (bucket: UsageBucket) => inScope(bucket).filter((row) => identities.keyOf(row) === identity.key);
return {
key: identity.key,
label: identity.label,
colorIndex: index,
removed: identity.removed,
- values: report.buckets.map((bucket) => bucketMetricValue(bucket, rowsOf(bucket), metric)),
+ values: report.buckets.map((bucket) => bucketMetricValue(bucket, rowsOf(bucket), metric, unpricedKeys)),
floors: report.buckets.map((bucket) => costIsFloor(rowsOf(bucket), metric)),
- unpriced: report.buckets.map((bucket) => costIsUnpriced(rowsOf(bucket), metric)),
+ unpriced: report.buckets.map((bucket) => costIsUnpriced(rowsOf(bucket), metric, unpricedKeys)),
};
});
}
@@ -564,8 +638,81 @@ export function reportHasPartialHistory(report: UsageReport, filter: UsageFilter
export function reportHasUnknownTokens(report: UsageReport, filter: UsageFilter): boolean {
return report.buckets.some((bucket) => {
- const rows = filterBucketRows(bucket, filter);
+ const rows = filterBucketRows(bucket, filter).filter(isModelRow);
const counters = aggregateCounters(rows);
return rows.length > 0 && !usageTokensAreKnown(counters);
});
}
+
+export type ServiceUsageRow = {
+ key: string;
+ /** The Source's identity, as the Source filter names it. */
+ label: string;
+ /** The current catalog's name for the service, else its ID; empty for the removed aggregate. */
+ service: string;
+ removed: boolean;
+ totals: ServiceTotals;
+};
+
+/**
+ * The search-service table: one row per live Source and service, busiest
+ * first, and every Source config let go folded into the one removed identity
+ * last. It follows the Source filter and pinned bucket as the model table does.
+ */
+export function serviceUsageRows(
+ report: UsageReport,
+ filter: UsageFilter,
+ pinnedKey: string | null,
+ text: UsageText,
+): ServiceUsageRow[] {
+ const buckets = pinnedKey === null ? report.buckets : report.buckets.filter((bucket) => bucket.key === pinnedKey);
+ const sources = usageIdentities(report, 'source', text);
+ const unpriced = unpricedServices(report);
+ const groups = new Map<string, UsageServiceBucketRow[]>();
+ for (const row of buckets.flatMap((bucket) => filterBucketRows(bucket, filter)).filter(isServiceRow)) {
+ const source = sources.keyOf(row);
+ const key = source === REMOVED_SOURCES_KEY ? source : pairKey(row.source_id, row.service_id);
+ groups.set(key, [...(groups.get(key) ?? []), row]);
+ }
+ return [...groups].map(([key, rows]) => {
+ const [first] = rows;
+ const removed = key === REMOVED_SOURCES_KEY;
+ const catalogLabel = report.services
+ .find((service) => service.source_id === first.source_id && service.service_id === first.service_id)
+ ?.service_label?.trim();
+ return {
+ key,
+ label: sources.get(sources.keyOf(first)).label,
+ service: removed ? '' : catalogLabel || first.service_id,
+ removed,
+ totals: aggregateServiceRows(rows, unpriced),
+ };
+ }).sort((left, right) => Number(left.removed) - Number(right.removed) || right.totals.requests - left.totals.requests);
+}
+
+export type ServiceMonth = {
+ /** The host's current month, `YYYY-MM`. */
+ month: string;
+ totals: ServiceTotals;
+ /** The report carries API-price value at all. */
+ priced: boolean;
+ /** A day of the month is missing history, so its counts are only a floor. */
+ partial: boolean;
+};
+
+/**
+ * One Source's search requests this month, from a daily report: the day
+ * buckets in the month of `to_day`, the host's local today rather than the
+ * browser's. A 60-day report covers every day of any month.
+ */
+export function serviceMonthUsage(report: UsageReport, sourceId: string): ServiceMonth {
+ const month = report.to_day.slice(0, 7);
+ const buckets = report.buckets.filter((bucket) => bucket.key.slice(0, 7) === month);
+ const rows = buckets.flatMap((bucket) => bucket.rows).filter(isServiceRow).filter((row) => row.source_id === sourceId);
+ return {
+ month,
+ totals: aggregateServiceRows(rows, unpricedServices(report)),
+ priced: reportIsPriced(report),
+ partial: buckets.some((bucket) => !bucket.history_complete),
+ };
+}
diff --git a/ui/src/components/workbench/HostedToolRow.test.tsx b/ui/src/components/workbench/HostedToolRow.test.tsx
index b3f49184f..7dbf86412 100644
--- a/ui/src/components/workbench/HostedToolRow.test.tsx
+++ b/ui/src/components/workbench/HostedToolRow.test.tsx
@@ -9,6 +9,7 @@ import { afterEach, describe, expect, it } from 'vitest';
import en from '../../i18n/en.json';
import zh from '../../i18n/zh.json';
import fixture from '../../lib/hostedActivity.fixture.json';
+import services from '../../lib/hostedServiceActivity.fixture.json';
import { groupFromWire } from '../../lib/agentActivity';
import { ActivityChip } from './AgentActivityGroup';
import { InstanceAuthorizationContext } from '../../context/InstanceAuthorizationContext';
@@ -213,3 +214,40 @@ describe('hosted tool cards', () => {
within(proxy).getByText('2 条帖子');
});
});
+
+describe('search service cards', () => {
+ // The cards `tests/test_hosted_activity.py` projects from a search chain and its Sources' current state, with the
+ // words both surfaces show for them: the note here is the sentence the IM line carries.
+ it.each(['en', 'zh'] as const)('MH-HOSTED-UI-008 (%s): names the service that ran, what it found and cost, and why it moved past a Source', (lng) => {
+ const { service_completed: completed, service_switch: switched, service_estimate: estimated, service_blocked: blocked } = services;
+ renderGroup([completed.payload, switched.payload, estimated.payload, blocked.payload], lng);
+
+ for (const { payload, [lng]: says } of [completed, switched, estimated]) {
+ const card = row(payload.call_id);
+ within(card).getByText(says.chip);
+ within(card).getByText(says.count);
+ within(card).getByText(says.cost);
+ const note = card.querySelector('[data-hosted-switch]');
+ expect(note?.textContent ?? null).toBe('note' in says ? says.note : null);
+ }
+
+ // A call that did not complete names every Source it reached, each with what it needs now.
+ const failed = row(blocked.payload.call_id);
+ within(failed).getByText(blocked[lng].status);
+ within(failed).getByText(blocked[lng].cost);
+ expect(failed.querySelector('[data-hosted-attempts]')?.textContent).toBe(blocked[lng].note);
+ // A service is named as its Source, never by its catalog service id.
+ expect(document.body.textContent).not.toMatch(/\/search/);
+ });
+
+ it('says who ran it, and reads a reason this client does not know yet as a failure', () => {
+ renderGroup([
+ services.service_completed.payload,
+ { ...services.service_blocked.payload, attempts: [{ ...services.service_blocked.payload.attempts[0], remedy_key: 'repair.someday' }] },
+ ]);
+ const card = row('call_ws1');
+ fireEvent.click(within(card).getByRole('button'));
+ within(card).getByText('Run by search service Tavily · ≈ $0.008');
+ expect(row('call_ws4').querySelector('[data-hosted-attempts]')?.textContent).toBe('Tavily failed');
+ });
+});
diff --git a/ui/src/components/workbench/HostedToolRow.tsx b/ui/src/components/workbench/HostedToolRow.tsx
index 2df18dde3..153c45961 100644
--- a/ui/src/components/workbench/HostedToolRow.tsx
+++ b/ui/src/components/workbench/HostedToolRow.tsx
@@ -31,9 +31,13 @@ const presetLabel = (provider: string | undefined): string | null =>
/** Who ran a call: its vendor's catalog label, else the Source's own name. A compatible endpoint's
* vendor id is `custom`, which names no vendor, so its name is the only thing that says where the
- * call ran. A vendor id with neither stays as it is, as for a row stored without a Source. */
-const runnerLabel = (card: HostedActivity): string | null =>
- presetLabel(card.provider) ?? card.source_name ?? card.provider ?? null;
+ * call ran. A search service is named by its Source first, as the user named it. A vendor id with
+ * neither stays as it is, as for a row stored without a Source. The IM line reads the same rule. */
+const runnerLabel = (card: HostedActivity): string | null => {
+ const vendor = presetLabel(card.provider);
+ if (vendor && card.executor_kind !== 'service') return vendor;
+ return card.source_name ?? vendor ?? card.provider ?? null;
+};
// Small per-call figures keep their first significant digits: $0.006, not $0.01.
const formatUsd = (usd: number): string => {
@@ -78,7 +82,7 @@ const useHostedCost = (card: HostedActivity): string | null => {
? t('chat.agentActivity.hosted.cost.included') as string
: cost.usd === undefined
? null
- : t(cost.basis === 'list' ? 'chat.agentActivity.hosted.cost.list' : 'chat.agentActivity.hosted.cost.reported', { usd: formatUsd(cost.usd) }) as string;
+ : t(cost.usd === 0 || (cost.basis !== 'list' && !cost.estimate) ? 'chat.agentActivity.hosted.cost.reported' : 'chat.agentActivity.hosted.cost.list', { usd: formatUsd(cost.usd) }) as string;
if (figure === null) return null;
const bounded = cost.at_least ? t('chat.agentActivity.hosted.cost.atLeast', { cost: figure }) as string : figure;
return cost.calls > 1 ? t('chat.agentActivity.hosted.cost.calls', { cost: bounded, count: cost.calls }) as string : bounded;
@@ -117,6 +121,14 @@ export const HostedModeChip: React.FC<{ card: HostedActivity }> = ({ card }) =>
);
}
if (!vendor) return null;
+ if (card.executor_kind === 'service') {
+ return (
+ <span className="inline-flex shrink-0 items-center gap-1 rounded-full border border-cyan/40 bg-cyan-soft px-2 py-px text-[11px] font-medium text-cyan-ink">
+ <Waypoints className="size-3" aria-hidden="true" />
+ {t('chat.agentActivity.hosted.mode.service', { provider: vendor })}
+ </span>
+ );
+ }
return card.mode === 'native' ? (
<span className="inline-flex shrink-0 items-center gap-1 rounded-full border border-mint/40 bg-mint-soft px-2 py-px text-[11px] font-medium text-mint-ink">
<Check className="size-3" aria-hidden="true" />
@@ -194,13 +206,46 @@ export const HostedImageFigure: React.FC<{ card: HostedActivity; image: HostedAc
);
};
+/**
+ * What a search chain's Sources did, in the words the producer chose for them (`core/hosted_activity.py`): for a
+ * completed call, the Sources it moved past before the one that answered; for one that did not complete, every
+ * Source it reached, each with what it needs now, else what happened to it. Both stay in view, collapsed or
+ * expanded, as the IM line carries them.
+ */
+const HostedAttemptNotes: React.FC<{ card: HostedActivity }> = ({ card }) => {
+ const { t } = useTranslation();
+ // A key the producer chose; one this client does not know yet reads as a plain failure.
+ const say = (key: string | undefined) => serverText(t, key && `chat.agentActivity.hosted.${key}`, 'chat.agentActivity.hosted.reason.failed');
+ if (hostedCompleted(card)) {
+ const note = card.switch;
+ if (!note) return null;
+ const failed = `${note.sources.join(t('chat.agentActivity.hosted.listSeparator'))} ${say(note.reason_key)}`;
+ return (
+ <p className="mx-1.5 mb-1 mt-0.5 flex items-center gap-1.5 rounded-md border border-gold/40 bg-gold/10 px-2.5 py-1.5 text-[11px] text-foreground" data-hosted-switch={card.call_id}>
+ <TriangleAlert className="size-3 shrink-0 text-gold-ink" aria-hidden="true" />
+ {t('chat.agentActivity.hosted.switch', { failed, provider: note.to })}
+ </p>
+ );
+ }
+ const items = (card.attempts ?? [])
+ .filter((attempt) => attempt.remedy_key || attempt.reason_key)
+ .map((attempt) => `${attempt.label} ${say(attempt.remedy_key ?? attempt.reason_key)}`);
+ if (items.length === 0) return null;
+ return (
+ <p className="mx-1.5 mb-1 mt-0.5 rounded-md border border-destructive/30 bg-destructive/5 px-2.5 py-1.5 text-[11px] text-destructive-ink" data-hosted-attempts={card.call_id}>
+ {items.join(t('chat.agentActivity.hosted.itemSeparator'))}
+ </p>
+ );
+};
+
const HostedDetail: React.FC<{ card: HostedActivity }> = ({ card }) => {
const { t } = useTranslation();
const cost = useHostedCost(card);
const completed = hostedCompleted(card);
const where = completed ? [card.source_name ?? runnerLabel(card), card.model].filter(Boolean).join(' · ') : '';
+ const ran = card.executor_kind === 'service' ? 'ranService' : RAN_KEY[card.mode];
const facts = [
- where && t(`chat.agentActivity.hosted.${RAN_KEY[card.mode]}`, { where }),
+ where && t(`chat.agentActivity.hosted.${ran}`, { where }),
completed && card.duration_ms !== undefined && t('chat.agentActivity.hosted.duration', { seconds: Math.max(1, Math.round(card.duration_ms / 1000)) }),
cost,
].filter(Boolean);
@@ -311,6 +356,7 @@ export const HostedToolRow: React.FC<{ card: HostedActivity }> = ({ card }) => {
{count && <span className="hidden shrink-0 text-[11px] text-muted sm:inline">{count}</span>}
<ChevronRight className={clsx('size-3.5 shrink-0 text-muted transition-transform', open && 'rotate-90')} aria-hidden="true" />
</button>
+ <HostedAttemptNotes card={card} />
<FallbackNote card={card} />
{open && <HostedDetail card={card} />}
</div>
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 322b8b7d7..3dbd6d8cd 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -1763,6 +1763,16 @@
"outputTokens": "Output tokens",
"totalTokens": "Total tokens"
},
+ "services": {
+ "title": "Search services",
+ "identity": "Source / service",
+ "billable": "Billable",
+ "uncertain_one": "+{{requests}} with unknown billing",
+ "uncertain_other": "+{{requests}} with unknown billing",
+ "reported": "Vendor-reported",
+ "accounting": "Search requests are not model calls: they stay out of the token and request figures above, and only their value at API price joins the total.",
+ "priceDate": "Search prices from {{date}}."
+ },
"failure": "The usage report could not be read.",
"retry": "Retry",
"cost": {
@@ -1771,6 +1781,9 @@
"fetching": "Fetching prices…",
"excluded_one": "{{tokens}} token has no price and is left out",
"excluded_other": "{{tokens}} tokens have no price and are left out",
+ "reported": "Vendors reported {{usd}}",
+ "excludedServices_one": "{{requests}} search request has no price and is left out",
+ "excludedServices_other": "{{requests}} search requests have no price and are left out",
"tableDate": "Price table from {{date}}",
"tableDateUnknown": "Price table date unknown",
"tableFetching": "Fetching the price table…"
@@ -2560,6 +2573,12 @@
"removeNote": "Removing this service stops using it for search. Other providers are unaffected.",
"addProvider": "Add provider",
"menu": "Search services (Tavily, Exa…)",
+ "month": "This month",
+ "monthRequests_one": "{{requests}} request",
+ "monthRequests_other": "{{requests}} requests",
+ "monthEstimate": "API list-price estimate {{usd}}",
+ "monthReported": "vendor-reported {{usd}}",
+ "openUsage": "View usage",
"vendor": {
"deepseek": "Search through the official DeepSeek provider. Only searches with results are billed; empty results, failures and timeouts are not.",
"tavily": "Basic web search with query-relevant snippets, designed for AI agents.",
@@ -2578,6 +2597,7 @@
"native": "A real request ran {{toolInline}} natively on this model. Display only; it doesn't change routing.",
"executor": "This model ran {{toolInline}} for other models as the executor. Display only; it doesn't change routing.",
"direct": "This model generated images on its image endpoint. Display only; it doesn't change routing.",
+ "service": "This search service ran {{toolInline}} in a real request. Display only; it doesn't change routing.",
"refused": "This Source refused {{toolInline}} in a real request on this model. Until you clear it, Vibey does it another way.",
"replay": "This model runs {{toolInline}} on this Source but refused earlier results sent back to it, so they go back as plain text."
},
@@ -5069,15 +5089,57 @@
"provider_image_unusable": "The provider returned an image that couldn't be used.",
"search_not_run": "The model answered without searching.",
"search_failed": "The provider's search failed.",
- "response_ended_early": "The response ended early."
+ "response_ended_early": "The response ended early.",
+ "service_key_invalid": "The search service key is invalid.",
+ "service_balance": "The search service account has no balance.",
+ "service_limit": "The search service limit has been reached.",
+ "service_unavailable": "The search service is unavailable.",
+ "service_refused": "The search service refused this query.",
+ "service_unreadable": "The search service returned an unreadable response.",
+ "search_query_too_long": "The search query is too long; shorten it and try again.",
+ "search_sources_blocked": "All search sources are blocked or disabled."
},
"mode": {
"native": "Native · {{provider}}",
"proxy": "Via {{provider}} proxy",
+ "service": "Through {{provider}}",
"direct": "Direct · {{provider}}",
"directModel": "{{model}} · {{source}}",
"proxyModel": "Via {{provider}} proxy · {{model}}"
},
+ "repair": {
+ "disabled": "needs web search enabled in Models › Tools",
+ "key": "needs a replacement key",
+ "reauthorize": "needs a new sign-in",
+ "balance": "needs an account top-up",
+ "balanceReenable": "needs an account top-up, then re-enabling in Models › Tools",
+ "limit": "needs a higher spending or usage limit",
+ "limitReenable": "needs a higher spending or usage limit, then re-enabling in Models › Tools",
+ "tavilyLimit": "needs a plan upgrade or a higher key usage limit (432), or a higher pay-as-you-go limit (433) in Tavily, then re-enabling in Models › Tools",
+ "plan": "needs a plan that includes this product",
+ "account": "needs the account restored by the provider",
+ "error": "needs attention in Models › Providers"
+ },
+ "reason": {
+ "failed": "failed",
+ "superseded": "failed on this request; a later action has since updated its state",
+ "service_key_invalid": "has an invalid key",
+ "service_balance": "is out of balance",
+ "service_limit": "reached its usage limit",
+ "service_unavailable": "was unavailable",
+ "service_refused": "refused this query",
+ "service_unreadable": "returned an unreadable response"
+ },
+ "skip": {
+ "blocked": "was blocked",
+ "disabled": "was not enabled for search",
+ "cooling": "was waiting to retry",
+ "query_too_long": "can't take a query this long",
+ "unavailable": "was unavailable"
+ },
+ "listSeparator": ", ",
+ "itemSeparator": "; ",
+ "switch": "{{failed}}; switched to {{provider}}",
"status": {
"failed": "Failed",
"incomplete": "Incomplete",
@@ -5102,6 +5164,7 @@
"ranNative": "Ran natively on {{where}}",
"ranProxy": "Run by proxy executor {{where}}",
"ranDirect": "Ran directly on {{where}}",
+ "ranService": "Run by search service {{where}}",
"fallback": {
"ranOn": "{{from}} doesn't support {{toolInline}}, so {{provider}} ({{source}}) ran it",
"ran": "{{from}} doesn't support {{toolInline}}, so {{provider}} ran it",
diff --git a/ui/src/i18n/zh.json b/ui/src/i18n/zh.json
index 613d717ec..70339b11a 100644
--- a/ui/src/i18n/zh.json
+++ b/ui/src/i18n/zh.json
@@ -1763,6 +1763,16 @@
"outputTokens": "输出 token",
"totalTokens": "总 token"
},
+ "services": {
+ "title": "搜索服务",
+ "identity": "供应商 / 服务",
+ "billable": "计费请求",
+ "uncertain_one": "另有 {{requests}} 次计费未知",
+ "uncertain_other": "另有 {{requests}} 次计费未知",
+ "reported": "厂商报告",
+ "accounting": "搜索请求不是模型调用:不计入上方的 token 和请求数,只有折合 API 价格计入合计。",
+ "priceDate": "搜索价格日期 {{date}}。"
+ },
"failure": "暂时没能读取用量报表。",
"retry": "重试",
"cost": {
@@ -1772,6 +1782,9 @@
"excluded_one": "{{tokens}} tokens 暂无价格,未计入",
"excluded_other": "{{tokens}} tokens 暂无价格,未计入",
"tableDate": "价格表日期 {{date}}",
+ "reported": "厂商报告 {{usd}}",
+ "excludedServices_one": "{{requests}} 次搜索请求暂无价格,未计入",
+ "excludedServices_other": "{{requests}} 次搜索请求暂无价格,未计入",
"tableDateUnknown": "暂无价格表日期",
"tableFetching": "正在获取价格表…"
}
@@ -2560,6 +2573,12 @@
"removeNote": "移除后不再用于搜索,其他供应商不受影响。",
"addProvider": "添加供应商",
"menu": "搜索服务(Tavily、Exa…)",
+ "month": "本月",
+ "monthRequests_one": "{{requests}} 次请求",
+ "monthRequests_other": "{{requests}} 次请求",
+ "monthEstimate": "按 API 标价估算 {{usd}}",
+ "monthReported": "厂商报告 {{usd}}",
+ "openUsage": "查看用量",
"vendor": {
"deepseek": "通过官方 DeepSeek 供应商搜索,有结果才计费,空结果、失败和超时不计费。",
"tavily": "为 AI Agent 设计的基础网页搜索,返回与搜索词相关的片段。",
@@ -2578,6 +2597,7 @@
"native": "最近一次真实调用在这个模型上原生执行了{{toolInline}}。只用于显示,不影响路由。",
"executor": "这个模型作为执行者,为其他模型执行了{{toolInline}}。只用于显示,不影响路由。",
"direct": "这个模型通过图片接口生成了图片。只用于显示,不影响路由。",
+ "service": "最近一次真实请求通过这个搜索服务执行了{{toolInline}}。只用于显示,不影响路由。",
"refused": "此供应商在这个模型的真实请求中拒绝了{{toolInline}}。清除前,Vibey 会改用其他方式完成。",
"replay": "这个模型能在此供应商上执行{{toolInline}},但拒绝回放历史结果,之后历史结果会以文本形式发回。"
},
@@ -5069,15 +5089,57 @@
"provider_image_unusable": "供应商返回的图片无法使用。",
"search_not_run": "模型没有搜索就直接作答了。",
"search_failed": "供应商的搜索失败了。",
- "response_ended_early": "回复提前结束了。"
+ "response_ended_early": "回复提前结束了。",
+ "service_key_invalid": "搜索服务密钥无效。",
+ "service_balance": "搜索服务账户余额不足。",
+ "service_limit": "搜索服务已达到用量上限。",
+ "service_unavailable": "搜索服务暂时不可用。",
+ "service_refused": "搜索服务拒绝了这次搜索。",
+ "service_unreadable": "搜索服务返回了无法读取的结果。",
+ "search_query_too_long": "搜索词太长,请缩短后重试。",
+ "search_sources_blocked": "所有搜索来源都被阻止或停用了。"
},
"mode": {
"native": "原生 · {{provider}}",
"proxy": "由 {{provider}} 代理",
+ "service": "通过 {{provider}}",
"direct": "{{provider}} 直连",
"directModel": "{{model}} · {{source}}",
"proxyModel": "由 {{provider}} 代理 · {{model}}"
},
+ "repair": {
+ "disabled": "需要在 模型 › 工具 中启用网页搜索",
+ "key": "需要更换密钥",
+ "reauthorize": "需要重新授权登录",
+ "balance": "需要充值",
+ "balanceReenable": "需要充值,然后在 模型 › 工具 中重新启用",
+ "limit": "需要提高消费或用量上限",
+ "limitReenable": "需要提高消费或用量上限,然后在 模型 › 工具 中重新启用",
+ "tavilyLimit": "需要在 Tavily 后台升级套餐或提高该密钥的用量上限(432),或提高按量上限(433),然后在 模型 › 工具 中重新启用",
+ "plan": "需要升级为包含此产品的套餐",
+ "account": "需要联系供应商恢复账户",
+ "error": "需要在 模型 › 供应商 中处理"
+ },
+ "reason": {
+ "failed": "失败",
+ "superseded": "这次请求失败,状态已由之后的操作更新",
+ "service_key_invalid": "密钥无效",
+ "service_balance": "余额不足",
+ "service_limit": "已达用量上限",
+ "service_unavailable": "暂时不可用",
+ "service_refused": "拒绝了这次搜索",
+ "service_unreadable": "返回了无法读取的结果"
+ },
+ "skip": {
+ "blocked": "当时被阻止",
+ "disabled": "当时未用于搜索",
+ "cooling": "当时正在等待重试",
+ "query_too_long": "不支持这么长的搜索词",
+ "unavailable": "当时不可用"
+ },
+ "listSeparator": "、",
+ "itemSeparator": ";",
+ "switch": "{{failed}},已改用 {{provider}}",
"status": {
"failed": "失败",
"incomplete": "未完成",
@@ -5102,6 +5164,7 @@
"ranNative": "原生执行:{{where}}",
"ranProxy": "代理执行:{{where}}",
"ranDirect": "直连执行:{{where}}",
+ "ranService": "搜索服务执行:{{where}}",
"fallback": {
"ranOn": "{{from}} 不支持{{toolInline}},已改用 {{provider}}({{source}})",
"ran": "{{from}} 不支持{{toolInline}},已改用 {{provider}}",
diff --git a/ui/src/lib/hostedActivity.ts b/ui/src/lib/hostedActivity.ts
index 455404395..ac7c89a9f 100644
--- a/ui/src/lib/hostedActivity.ts
+++ b/ui/src/lib/hostedActivity.ts
@@ -1,7 +1,8 @@
// A hosted tool call's card, as a ``toolcall`` row carries it in ``content.hosted``
-// (``core/hosted_activity.py``, version 1; the shared fixture is
-// ``hostedActivity.fixture.json``). The row's ``text`` is the IM line; the Web
-// renders the card from these fields instead.
+// (``core/hosted_activity.py``, version 1; the shared fixtures are
+// ``hostedActivity.fixture.json`` and, for search services,
+// ``hostedServiceActivity.fixture.json``). The row's ``text`` is the IM line; the
+// Web renders the card from these fields instead.
export type HostedToolName = 'web_search' | 'x_search' | 'image_generate';
@@ -13,6 +14,27 @@ export type HostedActivitySource = {
page_age?: string;
};
+/** One candidate a search chain reached, as the producer projected it now: ``label`` is the Source's current
+ * name, and ``reason_key`` (what happened) and ``remedy_key`` (what the Source needs now) are keys under
+ * ``chat.agentActivity.hosted``, decided once for the Web card and the IM line alike. */
+export type HostedActivityAttempt = {
+ source_id: string;
+ label: string;
+ kind: 'service' | 'model';
+ outcome: 'completed' | 'failed' | 'skipped';
+ error_code?: string;
+ skipped?: 'blocked' | 'disabled' | 'cooling' | 'query_too_long' | 'unavailable';
+ retry_at?: string;
+ needs_action?: string;
+ cost?: { basis: 'reported' | 'list' | 'included'; usd?: number; estimate?: boolean };
+ superseded?: boolean;
+ reason_key?: string;
+ remedy_key?: string;
+};
+
+/** A completed search that moved past Sources that failed or were blocked, and the Source that answered. */
+export type HostedActivitySwitch = { sources: string[]; reason_key: string; to: string };
+
export type HostedActivityImage = {
path: string;
mime: string;
@@ -40,6 +62,8 @@ export type HostedActivity = {
extra_queries?: string[];
/** Vendor id of whoever ran it: the response's for native, the executor's for proxy. */
provider?: string;
+ /** Whether a search service or a model executor ran it; absent when the record does not say. */
+ executor_kind?: 'service' | 'model';
source_id?: string;
source_name?: string;
model?: string;
@@ -51,13 +75,32 @@ export type HostedActivity = {
duration_ms?: number;
/** The Source that refused to run this search natively, so it ran by proxy instead; absent otherwise. */
fallback_from?: { source_id: string; source_name?: string };
- /** Absent when no price is known: unknown is never shown as zero. ``calls`` is how many calls it covers, and
- * ``at_least`` marks a lower bound: an attempt reported no price. */
- cost?: { basis: 'reported' | 'list' | 'included'; usd?: number; calls: number; at_least?: boolean };
+ /** Every candidate a search chain reached; absent for a record that has none, as a model-only chain's. */
+ attempts?: HostedActivityAttempt[];
+ switch?: HostedActivitySwitch;
+ /** Absent when no price is known: unknown is never shown as zero. ``calls`` is how many calls it covers,
+ * ``at_least`` marks a lower bound (an attempt reported no price), and ``estimate`` a vendor's own estimate. */
+ cost?: { basis: 'reported' | 'list' | 'included'; usd?: number; calls: number; estimate?: boolean; at_least?: boolean };
};
const TOOLS: readonly string[] = ['web_search', 'x_search', 'image_generate'];
const STATUSES: readonly string[] = ['completed', 'failed', 'incomplete', 'pending'];
+const optionalString = (value: unknown): boolean => value === undefined || typeof value === 'string';
+const attemptFrom = (raw: unknown): HostedActivityAttempt | undefined => {
+ if (!raw || typeof raw !== 'object') return undefined;
+ const attempt = raw as Record<string, unknown>;
+ if (typeof attempt.source_id !== 'string' || typeof attempt.label !== 'string') return undefined;
+ if (attempt.kind !== 'service' && attempt.kind !== 'model') return undefined;
+ if (attempt.outcome !== 'completed' && attempt.outcome !== 'failed' && attempt.outcome !== 'skipped') return undefined;
+ if (!optionalString(attempt.reason_key) || !optionalString(attempt.remedy_key)) return undefined;
+ return attempt as unknown as HostedActivityAttempt;
+};
+const switchFrom = (raw: unknown): HostedActivitySwitch | undefined => {
+ if (!raw || typeof raw !== 'object') return undefined;
+ const note = raw as Record<string, unknown>;
+ if (!Array.isArray(note.sources) || !note.sources.every((name) => typeof name === 'string')) return undefined;
+ return typeof note.reason_key === 'string' && typeof note.to === 'string' ? note as unknown as HostedActivitySwitch : undefined;
+};
/** The card a row carries, or undefined for anything that is not one this client reads. */
export const hostedActivityFrom = (raw: unknown): HostedActivity | undefined => {
@@ -71,6 +114,8 @@ export const hostedActivityFrom = (raw: unknown): HostedActivity | undefined =>
...(card as unknown as HostedActivity),
sources: Array.isArray(card.sources) ? (card.sources as HostedActivitySource[]).filter((s) => typeof s?.url === 'string' || typeof s?.title === 'string') : [],
images: Array.isArray(card.images) ? (card.images as HostedActivityImage[]).filter((i) => typeof i?.path === 'string') : [],
+ attempts: Array.isArray(card.attempts) ? card.attempts.map(attemptFrom).filter((attempt): attempt is HostedActivityAttempt => attempt !== undefined) : undefined,
+ switch: switchFrom(card.switch),
};
};
diff --git a/ui/src/lib/hostedServiceActivity.fixture.json b/ui/src/lib/hostedServiceActivity.fixture.json
new file mode 100644
index 000000000..e85b9eb5e
--- /dev/null
+++ b/ui/src/lib/hostedServiceActivity.fixture.json
@@ -0,0 +1,206 @@
+{
+ "_comment": "Search-service cards (web-search-services.md §4.3, §6.5): the content.hosted payload core/hosted_activity.py projects from a chain with attempts and its Sources' current state, and the words each surface shows for it. tests/test_hosted_activity.py builds each payload from canonical C-1 records and checks the IM line; HostedToolRow.test.tsx renders the payload and checks the card. The note is the same sentence on both surfaces.",
+ "service_completed": {
+ "payload": {
+ "version": 1,
+ "call_id": "call_ws1",
+ "tool": "web_search",
+ "mode": "proxy",
+ "status": "completed",
+ "subject": "DeepSeek search API pricing",
+ "provider": "tavily",
+ "source_id": "src_tavily01",
+ "source_name": "Tavily",
+ "executor_kind": "service",
+ "sources": [
+ { "url": "https://api-docs.deepseek.com/guides/search-tool", "title": "Search tool", "snippet": "One HTTPS request returns ranked results." },
+ { "url": "https://api-docs.deepseek.com/quick_start/pricing", "title": "Models & Pricing" },
+ { "url": "https://www.tavily.com/pricing", "title": "Tavily pricing" },
+ { "url": "https://exa.ai/pricing", "title": "Exa pricing" },
+ { "url": "https://news.example.com/deepseek-search", "title": "DeepSeek adds a search API", "page_age": "2 days ago" }
+ ],
+ "images": [],
+ "attempts": [
+ { "source_id": "src_tavily01", "label": "Tavily", "kind": "service", "outcome": "completed", "cost": { "basis": "list", "usd": 0.008 } }
+ ],
+ "cost": { "basis": "list", "usd": 0.008, "calls": 1 }
+ },
+ "en": {
+ "chip": "Through Tavily",
+ "count": "5 sources",
+ "cost": "≈ $0.008",
+ "line": "🔎 Web search “DeepSeek search API pricing” · Tavily · 5 sources · ≈ $0.008"
+ },
+ "zh": {
+ "chip": "通过 Tavily",
+ "count": "5 个来源",
+ "cost": "≈ $0.008",
+ "line": "🔎 网页搜索 “DeepSeek search API pricing” · Tavily · 5 个来源 · ≈ $0.008"
+ }
+ },
+ "service_switch": {
+ "payload": {
+ "version": 1,
+ "call_id": "call_ws2",
+ "tool": "web_search",
+ "mode": "proxy",
+ "status": "completed",
+ "subject": "DeepSeek search API pricing",
+ "provider": "deepseek",
+ "source_id": "src_deepseek1",
+ "source_name": "DeepSeek",
+ "executor_kind": "service",
+ "sources": [
+ { "url": "https://api-docs.deepseek.com/guides/search-tool", "title": "Search tool", "snippet": "One HTTPS request returns ranked results." },
+ { "url": "https://api-docs.deepseek.com/quick_start/pricing", "title": "Models & Pricing" },
+ { "url": "https://www.tavily.com/pricing", "title": "Tavily pricing" },
+ { "url": "https://exa.ai/pricing", "title": "Exa pricing" },
+ { "url": "https://news.example.com/deepseek-search", "title": "DeepSeek adds a search API", "page_age": "2 days ago" }
+ ],
+ "images": [],
+ "attempts": [
+ {
+ "source_id": "src_tavily01",
+ "label": "Tavily",
+ "kind": "service",
+ "outcome": "failed",
+ "error_code": "service_key_invalid",
+ "reason_key": "reason.service_key_invalid",
+ "remedy_key": "repair.key",
+ "cost": { "basis": "list", "usd": 0 }
+ },
+ { "source_id": "src_deepseek1", "label": "DeepSeek", "kind": "service", "outcome": "completed", "cost": { "basis": "list", "usd": 0.00075 } }
+ ],
+ "switch": { "sources": ["Tavily"], "reason_key": "reason.service_key_invalid", "to": "DeepSeek" },
+ "cost": { "basis": "list", "usd": 0.00075, "calls": 1 }
+ },
+ "en": {
+ "chip": "Through DeepSeek",
+ "count": "5 sources",
+ "cost": "≈ $0.0008",
+ "note": "Tavily has an invalid key; switched to DeepSeek",
+ "line": "🔎 Web search “DeepSeek search API pricing” · Tavily has an invalid key; switched to DeepSeek · 5 sources · ≈ $0.0008"
+ },
+ "zh": {
+ "chip": "通过 DeepSeek",
+ "count": "5 个来源",
+ "cost": "≈ $0.0008",
+ "note": "Tavily 密钥无效,已改用 DeepSeek",
+ "line": "🔎 网页搜索 “DeepSeek search API pricing” · Tavily 密钥无效,已改用 DeepSeek · 5 个来源 · ≈ $0.0008"
+ }
+ },
+ "service_estimate": {
+ "payload": {
+ "version": 1,
+ "call_id": "call_ws3",
+ "tool": "web_search",
+ "mode": "proxy",
+ "status": "completed",
+ "subject": "DeepSeek search API pricing",
+ "provider": "exa",
+ "source_id": "src_exa00001",
+ "source_name": "Exa",
+ "executor_kind": "service",
+ "sources": [
+ { "url": "https://api-docs.deepseek.com/guides/search-tool", "title": "Search tool", "snippet": "One HTTPS request returns ranked results." },
+ { "url": "https://api-docs.deepseek.com/quick_start/pricing", "title": "Models & Pricing" },
+ { "url": "https://www.tavily.com/pricing", "title": "Tavily pricing" },
+ { "url": "https://exa.ai/pricing", "title": "Exa pricing" },
+ { "url": "https://news.example.com/deepseek-search", "title": "DeepSeek adds a search API", "page_age": "2 days ago" }
+ ],
+ "images": [],
+ "attempts": [
+ {
+ "source_id": "src_tavily01",
+ "label": "Tavily",
+ "kind": "service",
+ "outcome": "skipped",
+ "skipped": "cooling",
+ "retry_at": "2026-10-21T04:30:00Z",
+ "reason_key": "skip.cooling"
+ },
+ {
+ "source_id": "src_exa00001",
+ "label": "Exa",
+ "kind": "service",
+ "outcome": "completed",
+ "cost": { "basis": "reported", "usd": 0.008, "estimate": true }
+ }
+ ],
+ "cost": { "basis": "reported", "usd": 0.008, "calls": 1, "estimate": true }
+ },
+ "en": {
+ "chip": "Through Exa",
+ "count": "5 sources",
+ "cost": "≈ $0.008",
+ "line": "🔎 Web search “DeepSeek search API pricing” · Exa · 5 sources · ≈ $0.008"
+ },
+ "zh": {
+ "chip": "通过 Exa",
+ "count": "5 个来源",
+ "cost": "≈ $0.008",
+ "line": "🔎 网页搜索 “DeepSeek search API pricing” · Exa · 5 个来源 · ≈ $0.008"
+ }
+ },
+ "service_blocked": {
+ "payload": {
+ "version": 1,
+ "call_id": "call_ws4",
+ "tool": "web_search",
+ "mode": "proxy",
+ "status": "failed",
+ "error": "every search source is blocked or turned off",
+ "error_code": "search_sources_blocked",
+ "subject": "DeepSeek search API pricing",
+ "source_id": "src_deepseek1",
+ "source_name": "DeepSeek",
+ "executor_kind": "service",
+ "sources": [],
+ "images": [],
+ "attempts": [
+ {
+ "source_id": "src_tavily01",
+ "label": "Tavily",
+ "kind": "service",
+ "outcome": "skipped",
+ "skipped": "blocked",
+ "needs_action": "models.source.needs_action.credential_revoked",
+ "reason_key": "reason.service_key_invalid",
+ "remedy_key": "repair.key"
+ },
+ {
+ "source_id": "src_exa00001",
+ "label": "Exa",
+ "kind": "service",
+ "outcome": "skipped",
+ "skipped": "blocked",
+ "needs_action": "models.source.needs_action.balance_exhausted",
+ "reason_key": "reason.service_balance",
+ "remedy_key": "repair.balanceReenable"
+ },
+ {
+ "source_id": "src_deepseek1",
+ "label": "DeepSeek",
+ "kind": "service",
+ "outcome": "failed",
+ "error_code": "service_unavailable",
+ "reason_key": "reason.service_unavailable",
+ "cost": { "basis": "list", "usd": 0 }
+ }
+ ],
+ "cost": { "basis": "list", "usd": 0, "calls": 1 }
+ },
+ "en": {
+ "status": "Failed",
+ "cost": "$0",
+ "note": "Tavily needs a replacement key; Exa needs an account top-up, then re-enabling in Models › Tools; DeepSeek was unavailable",
+ "line": "🔎 Web search “DeepSeek search API pricing” · failed: all search sources are blocked or disabled · Tavily needs a replacement key; Exa needs an account top-up, then re-enabling in Models › Tools; DeepSeek was unavailable · $0"
+ },
+ "zh": {
+ "status": "失败",
+ "cost": "$0",
+ "note": "Tavily 需要更换密钥;Exa 需要充值,然后在 模型 › 工具 中重新启用;DeepSeek 暂时不可用",
+ "line": "🔎 网页搜索 “DeepSeek search API pricing” · 失败:所有搜索来源都被阻止或停用了 · Tavily 需要更换密钥;Exa 需要充值,然后在 模型 › 工具 中重新启用;DeepSeek 暂时不可用 · $0"
+ }
+ }
+}
diff --git a/vibe/i18n/en.json b/vibe/i18n/en.json
index d23276243..ff08c59d0 100644
--- a/vibe/i18n/en.json
+++ b/vibe/i18n/en.json
@@ -1855,7 +1855,15 @@
"provider_image_unusable": "the provider returned an image that couldn't be used",
"search_not_run": "the model answered without searching",
"search_failed": "the provider's search failed",
- "response_ended_early": "the response ended early"
+ "response_ended_early": "the response ended early",
+ "service_key_invalid": "the search service key is invalid",
+ "service_balance": "the search service account has no balance",
+ "service_limit": "the search service limit has been reached",
+ "service_unavailable": "the search service is unavailable",
+ "service_refused": "the search service refused this query",
+ "service_unreadable": "the search service returned an unreadable response",
+ "search_query_too_long": "the search query is too long; shorten it and try again",
+ "search_sources_blocked": "all search sources are blocked or disabled"
},
"tool": {
"web_search": "Web search",
@@ -1885,6 +1893,39 @@
"calls": "{cost} for {calls} calls",
"atLeast": "at least {cost}"
},
+ "repair": {
+ "disabled": "needs web search enabled in Models › Tools",
+ "key": "needs a replacement key",
+ "reauthorize": "needs a new sign-in",
+ "balance": "needs an account top-up",
+ "balanceReenable": "needs an account top-up, then re-enabling in Models › Tools",
+ "limit": "needs a higher spending or usage limit",
+ "limitReenable": "needs a higher spending or usage limit, then re-enabling in Models › Tools",
+ "tavilyLimit": "needs a plan upgrade or a higher key usage limit (432), or a higher pay-as-you-go limit (433) in Tavily, then re-enabling in Models › Tools",
+ "plan": "needs a plan that includes this product",
+ "account": "needs the account restored by the provider",
+ "error": "needs attention in Models › Providers"
+ },
+ "reason": {
+ "failed": "failed",
+ "superseded": "failed on this request; a later action has since updated its state",
+ "service_key_invalid": "has an invalid key",
+ "service_balance": "is out of balance",
+ "service_limit": "reached its usage limit",
+ "service_unavailable": "was unavailable",
+ "service_refused": "refused this query",
+ "service_unreadable": "returned an unreadable response"
+ },
+ "skip": {
+ "blocked": "was blocked",
+ "disabled": "was not enabled for search",
+ "cooling": "was waiting to retry",
+ "query_too_long": "can't take a query this long",
+ "unavailable": "was unavailable"
+ },
+ "listSeparator": ", ",
+ "itemSeparator": "; ",
+ "switch": "{failed}; switched to {provider}",
"status": {
"failed": "failed: {error}",
"incomplete": "incomplete: {error}",
diff --git a/vibe/i18n/zh.json b/vibe/i18n/zh.json
index 5bd721b6d..682633738 100644
--- a/vibe/i18n/zh.json
+++ b/vibe/i18n/zh.json
@@ -1855,7 +1855,15 @@
"provider_image_unusable": "供应商返回的图片无法使用",
"search_not_run": "模型没有搜索就直接作答了",
"search_failed": "供应商的搜索失败了",
- "response_ended_early": "回复提前结束了"
+ "response_ended_early": "回复提前结束了",
+ "service_key_invalid": "搜索服务密钥无效",
+ "service_balance": "搜索服务账户余额不足",
+ "service_limit": "搜索服务已达到用量上限",
+ "service_unavailable": "搜索服务暂时不可用",
+ "service_refused": "搜索服务拒绝了这次搜索",
+ "service_unreadable": "搜索服务返回了无法读取的结果",
+ "search_query_too_long": "搜索词太长,请缩短后重试",
+ "search_sources_blocked": "所有搜索来源都被阻止或停用了"
},
"tool": {
"web_search": "网页搜索",
@@ -1885,6 +1893,39 @@
"calls": "{cost}({calls} 次调用)",
"atLeast": "至少 {cost}"
},
+ "repair": {
+ "disabled": "需要在 模型 › 工具 中启用网页搜索",
+ "key": "需要更换密钥",
+ "reauthorize": "需要重新授权登录",
+ "balance": "需要充值",
+ "balanceReenable": "需要充值,然后在 模型 › 工具 中重新启用",
+ "limit": "需要提高消费或用量上限",
+ "limitReenable": "需要提高消费或用量上限,然后在 模型 › 工具 中重新启用",
+ "tavilyLimit": "需要在 Tavily 后台升级套餐或提高该密钥的用量上限(432),或提高按量上限(433),然后在 模型 › 工具 中重新启用",
+ "plan": "需要升级为包含此产品的套餐",
+ "account": "需要联系供应商恢复账户",
+ "error": "需要在 模型 › 供应商 中处理"
+ },
+ "reason": {
+ "failed": "失败",
+ "superseded": "这次请求失败,状态已由之后的操作更新",
+ "service_key_invalid": "密钥无效",
+ "service_balance": "余额不足",
+ "service_limit": "已达用量上限",
+ "service_unavailable": "暂时不可用",
+ "service_refused": "拒绝了这次搜索",
+ "service_unreadable": "返回了无法读取的结果"
+ },
+ "skip": {
+ "blocked": "当时被阻止",
+ "disabled": "当时未用于搜索",
+ "cooling": "当时正在等待重试",
+ "query_too_long": "不支持这么长的搜索词",
+ "unavailable": "当时不可用"
+ },
+ "listSeparator": "、",
+ "itemSeparator": ";",
+ "switch": "{failed},已改用 {provider}",
"status": {
"failed": "失败:{error}",
"incomplete": "未完成:{error}",
diff --git a/vibe/model_hub_runtime/api_key_vendors.py b/vibe/model_hub_runtime/api_key_vendors.py
index fbc425c1c..db223a984 100644
--- a/vibe/model_hub_runtime/api_key_vendors.py
+++ b/vibe/model_hub_runtime/api_key_vendors.py
@@ -226,6 +226,7 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
entries: list[APIKeyVendorCatalogEntry] = []
seen_ids: set[str] = set()
+ seen_service_ids: set[str] = set()
for item in payload:
if not isinstance(item, dict):
raise ValueError("api-key vendor catalog is invalid")
@@ -248,6 +249,9 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
)
):
raise ValueError("api-key vendor catalog is invalid")
+ search = _validate_search_catalog(item.get("search"), protocol=protocol)
+ if search is not None and search["service_id"] in seen_service_ids:
+ raise ValueError("api-key vendor catalog is invalid")
entries.append(
APIKeyVendorCatalogEntry(
id=vendor_id,
@@ -255,10 +259,12 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
official_base_url=official_base_url,
protocol=protocol,
models_dev_provider=models_dev_provider.strip() if models_dev_provider else None,
- search=_validate_search_catalog(item.get("search"), protocol=protocol),
+ search=search,
)
)
seen_ids.add(vendor_id)
+ if search is not None:
+ seen_service_ids.add(search["service_id"])
return tuple(entries)