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.

docs(model-hub): hosted tools design v2: passive, default-on, simpler (#2635)

Call Whitee8a3e5ca8247
diff --git a/docs/plans/model-hub-capability-model.md b/docs/plans/model-hub-capability-model.md
index b8768b775..4fa7573da 100644
--- a/docs/plans/model-hub-capability-model.md
+++ b/docs/plans/model-hub-capability-model.md
@@ -1,7 +1,7 @@
# Model Hub capability model
-Status: **design**, 2026-10-13. Consumers: [`vibey-hosted-tools.md`](vibey-hosted-tools.md) and the effort menu
-(avibe-bot/avibe#2539). It extends [`model-hub-reasoning-intent.md`](model-hub-reasoning-intent.md) and
+Status: **design**, 2026-10-13; evidence made passive-only on 2026-10-15 with hosted tools design v2 (no probes).
+Consumers: [`vibey-hosted-tools.md`](vibey-hosted-tools.md) and the effort menu (avibe-bot/avibe#2539). It extends [`model-hub-reasoning-intent.md`](model-hub-reasoning-intent.md) and
[`model-hub-reasoning-tiers.md`](model-hub-reasoning-tiers.md); it does not replace their forwarding rule.
## 1. Problem
@@ -28,16 +28,18 @@ fact apart and gives each one owner.
| --- | --- | --- | --- | --- |
| **Base** | (provider, model) | models.dev, cached by `vibe/models_dev_catalog.py` | context and output limits, modalities, `tool_call`, `reasoning`, `reasoning_options` (wire effort values), token prices including context tiers (§6) | anything about a specific Source or relay |
| **Overlay** | provider model family, per protocol | Avibe. `vibe/data/backend_models.json` becomes the one overlay: its backend rows plus a new provider-neutral `providers` section (§4) | corrections and additions to the base: wire effort tiers where models.dev is wrong or late; **client presets** that never go on the wire (Codex `ultra`); **hosted tools** the provider offers for the model on that protocol; hosted-tool prices (§6) | per-Source truth; an allowlist |
-| **Evidence** | (Source, model, feature) | Model Hub state, next to Source health | the outcome of a live probe, or negative evidence learned from a real upstream error, with time, basis and scope | priors |
+| **Evidence** | (Source, model, feature) | Model Hub state, next to Source health | what real requests showed: negative evidence from a real upstream error, and positive evidence from a real response that carried the feature (display only), with time, wire stamp and scope | priors; anything learned without a real request the user's turn made |
Rules:
1. **Base and overlay are priors.** They decide what Avibe offers and shows before anything is known about a Source.
They never block a request (reasoning-intent decision of 2026-09-08: capability declarations are not an
allowlist).
-2. **Evidence decides routing.** It is the only layer that may change what a hop receives.
-3. **The #2505 rule applies to every fact.** Unknown is not negative. Only explicit negative evidence excludes, and
- only positive evidence enables a feature whose failure is terminal.
+2. **Negative evidence decides routing.** It is the only layer that may take a feature away from a hop. Positive
+ evidence never changes routing; it only tells the user what ran (`vibey-hosted-tools.md` §8).
+3. **The #2505 rule applies to every fact.** Unknown is not negative. Only explicit negative evidence excludes.
+ Since hosted tools design v2, a hosted tool the priors offer is assumed on a hop until a real request refuses it:
+ nothing is probed, and a refusal before output costs one re-rendered request (`vibey-hosted-tools.md` §3.5).
4. **One overlay.**
- `backend_models.json` already overlays efforts for native backends.
- Its backend rows gain `client_presets`, effort names a client maps before sending (Codex `ultra`). These are
@@ -56,7 +58,8 @@ Rules:
### 3.1 Record
-One record per (`source_id`, `model_id`, `feature`). Absence of a record is `unknown`. The persisted shape is
+At most one record per (`source_id`, `model_id`, `feature`, `status`): a `verified` (display) and an `unsupported`
+(routing) record for the same feature coexist. Absence of a record is `unknown`. The persisted shape is
below, and [`model-hub-contracts/capability-evidence.schema.json`](model-hub-contracts/capability-evidence.schema.json)
is its JSON Schema. The store is `core/handlers/model_hub/capability_evidence.py`.
@@ -64,16 +67,17 @@ is its JSON Schema. The store is `core/handlers/model_hub/capability_evidence.py
| --- | --- |
| `version` | `1` |
| `source_id`, `model_id` | non-empty |
-| `feature` | `{kind: "effort", name}` or `{kind: "hosted_tool", name: "web_search" \| "x_search" \| "image_generation", aspect: "call" \| "replay"}`; `image_generation` has `call` only |
-| `status` | `verified` or `unsupported` |
-| `basis` | `probe` (a live probe the user started) or `observed` (learned from a real request's error) |
+| `feature` | `{kind: "effort", name}` or `{kind: "hosted_tool", name: "web_search" \| "x_search" \| "image_generate", aspect: "call" \| "replay"}`; `image_generate` has `call` only |
+| `status` | `verified` (a real response carried the feature; display only) or `unsupported` (a narrow rule fired) |
+| `basis` | `observed`: learned from a real request. There is no other basis (v1's `probe` is gone). |
| `observed_at` | UTC timestamp |
-| `engine` | engine wire at that time: the shipped engine manifest's `hosted_wire` (the oldest release whose hosted passthrough is byte-identical, kept by the engine release gate), else its asset release; a change makes `probe` evidence stale (§3.3) |
-| `shape` | version of the request shape that produced the record; a change makes `probe` evidence stale |
-| `detail` | required when `basis` is `observed`: the HTTP status and upstream machine code, e.g. `400 invalid_value`, at most 64 characters, never upstream text |
+| `mode` | `verified` records only: how the call ran, `native`, `executor` or `direct` (`vibey-hosted-tools.md` §3.2) |
+| `wire` | the wire stamp the record was observed under: the engine release, the Avibe release, and a digest of the Source's rendered engine entry, credentials and model list excluded (§3.3) |
+| `detail` | required when `status` is `unsupported`: the HTTP status and upstream machine code, e.g. `400 invalid_value`, at most 64 characters, never upstream text |
| `source_identity` | digest of `retry.source_identity` when the record was written |
-`observed` evidence is always `unsupported`.
+Records an rc build wrote with `basis: probe`, `shape` or `image_generation` do not validate, so they are pruned at
+the next write (pre-release state, no migration).
Records live in the Model Hub state directory (`model_hub_capability_evidence.json`). They follow Source identity:
`retry.source_identity` covers kind, vendor, protocol, channel, base URL, credential and credential generation.
@@ -97,49 +101,56 @@ no marker, and a pending one's marker becomes its generation.
- `Unsupported tool type: <type>` for a type the request declared, matched to a catalog tool through the
overlay's declaration for that Source and model → hosted tool `call`;
- `Invalid encrypted_content in search_result block` while the request replays a web-search result → hosted
- tool `web_search` `replay`.
+ tool `web_search` `replay`;
+ - xAI's plain-text `Could not decrypt the provided encrypted_content` (no code) while the request replays an xAI
+ payload: its status waits for the Vibey lane's xAI A/B (stale ciphertext versus unsupported). Until then it
+ writes no evidence and only turns replay off for that Source for the rest of the turn.
+- **Positive, display only.** A served response that carries the provider's own item for a hosted tool the request
+ declared natively writes `verified` for the serving (Source, model, tool, `call`); a proxy executor call and a
+ successful image call do the same for the Source that ran them. It is written only when the state changes or the
+ existing record is over an hour old, so the evidence file is not rewritten per response
+ (`vibey-hosted-tools.md` §3.2).
- **Generic errors never create evidence.** That covers 5xx, overload, rate limit, auth, and any 400 that does not
name the feature.
- **What happens to the request.**
- An effort rule match fails the request as it does today. The next request skips that hop (§3.4).
- - A hosted-content rule match on a pinned request becomes `pin_unavailable`. Vibey re-sends the same request in
- portable form at once (`vibey-hosted-tools.md` §3.5).
-- Negative `observed` evidence expires after 7 days. Relays change, and an expired record falls back to the priors.
- A user's re-verify replaces it at once.
-
-### 3.3 Probes and re-verification
-
-- **A probe is a real upstream call.** It costs money (about $0.01–0.05; the 2026-10-13 spike measured it). It
- runs only on an eligible credential, and a Claude subscription Source is never eligible
- (`vibey-hosted-tools.md` §3.4). It runs only on an explicit user action:
- - enabling a hosted tool for a Source (or choosing it as the proxy executor);
- - the Source card's *Re-verify*;
- - confirming one pending re-verification that the UI lists (below).
-
- A probe never runs as a silent background job.
-- **The probe spec belongs to the feature.**
- - Hosted tools: [`vibey-hosted-tools.md`](vibey-hosted-tools.md) §3.2.
- - Efforts: one minimal request at that effort. Only the efforts a user actually selects are ever probed.
-- **Probe evidence becomes stale** on an engine upgrade that changes `hosted_wire`, a probe-shape change, or when it is 30 days old. A byte-identical engine upgrade keeps `hosted_wire`, so it re-probes nothing.
- - **Current-wire staleness** (the record's `engine` or `shape` differs from the current one) matters for hosted
- tools. Their positive evidence is needed because a native failure can be silent (§3.4). Evidence taken on another
- wire cannot vouch for this one, and a silent drop would never trip a narrow rule. So stale hosted-tool `call` and
- `replay` evidence counts as unknown for routing: proxy mode and synthetic replay, both lossless.
- - **Age-only staleness** keeps routing as it did: the wire Avibe sends has not changed.
- - **Effort evidence is unchanged.** It is negative only, and stale negative evidence still skips the hop until it
- expires.
- - The Source card marks stale records "re-verify", and Models lists them with one confirm action. After an engine
- upgrade the Tools tab says why native turned into proxy (`vibey-hosted-tools.md` §6.1).
-- **Positive evidence is demoted** by a narrow negative rule (§3.2) on a later real request.
+ - A hosted-content rule match on a pinned request becomes `pin_unavailable` with a machine-readable `reason`. Vibey
+ re-resolves the hop, whose fresh facts now name that tool as unsupported, and resends with the same-named function
+ (`vibey-hosted-tools.md` §3.5).
+- **How long negative evidence lasts** (owner decision, 2026-10-15): one rule for efforts and hosted tools. There is
+ no time limit. A record stays until one of these clears it:
+ - the user clears it: a hosted-tool refusal in Models → Tools (`vibey-hosted-tools.md` §3.3, §8.1), an effort
+ refusal on its Source chip (§5);
+ - its wire stamp no longer matches (§3.3), which happens on its own when the Source's config, the engine release
+ or the Avibe release changes.
+
+### 3.3 No probes; the wire stamp
+
+- **Nothing probes.** Since hosted tools design v2 (2026-10-15) no component calls a provider to learn a capability:
+ not on a user action, not in the background. Efforts were never probed; hosted tools no longer are. Every record
+ comes from a real request in a turn the user started (§3.2).
+- **Negative evidence never outlives the wire it was learned on.** Each record carries `wire`: the engine release,
+ the Avibe release, and a digest of the Source's rendered engine entry (what Avibe writes into the engine config for
+ that Source), credentials and the model list excluded. The Avibe release covers what Avibe itself sends: the
+ bundled overlay's declarations and `include` values and the adapters' request shape, so an update that fixes a
+ rejected declaration is tried again at once. Refusals are relearned once per release, each at the cost of one
+ re-rendered request. An `unsupported` record whose stamp differs from the current one reads as unknown, for
+ efforts and hosted tools alike; a `verified` record is display-only history and is kept. So a refusal learned under one engine or one rendered config cannot survive a
+ change that could reverse it: an engine upgrade, or a rendering change such as the `is-compat` flag for xAI
+ (#2620), which changes what xAI receives for replayed reasoning. A change on the provider's side, which the stamp
+ cannot see, waits for the user's clear.
+- **What goes.** v1's `shape` field, probe-shape staleness, age-based re-verification, and the `hosted_wire`
+ manifest field (never introduced; `engine_stamp()` loses its `hosted_wire` branch). Positive evidence needed them
+ because it vouched for a wire; it no longer vouches for anything.
### 3.4 How layers resolve
| Consumer | Rule |
| --- | --- |
| Effort menu for a model on an Agent | each hop's declared tiers, then the union across hops. A hop's declared tiers follow `model-hub-reasoning-tiers.md`'s ladder: an upstream reasoning signal (the protocol's ladder, bounded by the model's catalog row when it has one), else the bundled backend row's efforts minus that row's `client_presets` (provenance `catalog`; it outranks a user list, with a visible override event), else the user's list, else models.dev `reasoning_options` when the catalog row is built. A persisted `catalog` list is also read without `client_presets`, since released builds wrote them, and Vibey's own model rows always drop them at config load (3.2.0 saved rows with Codex's `ultra`; Vibey is never the client a preset belongs to, and no provider documents `ultra` as a wire effort). A user-authored Source list is never filtered. The overlay's `wire_efforts` slots in before the backend row once a vendor needs it; no shipped entry sets it yet. A tier is omitted only if **every** hop that can serve the model has negative evidence for it: every hop the route would try or wait for, exactly the hops whose refusal ends a request in `effort_unsupported`. A tier with negative evidence on some hops is shown with "not on: <Source>". Evidence is keyed by the token a client puts on the wire, which can differ from the menu value: Vibey sends menu `minimal` to Anthropic as `low`. So Model Hub decides both in menu values, where routing decides, and the picker's own read (`GET /api/models/agents/<backend>/models`, an Editor surface) carries the result per model as the response-only `effort_menu`. Vibey's adapters map each menu value through the one function their request builders use (`registry.sent_effort`); a native CLI sends the value as the menu names it. The chain API keeps each hop's read-only `refused_efforts` (`agent-chain.schema.json`) for the evidence detail. |
-| Effort at request time | Forwarded unchanged (reasoning-intent). A hop with **negative** evidence for that effort is skipped for this request, as if it were not a candidate. If no candidate remains, the request fails before invocation with `effort_unsupported` naming the effort and the Sources, instead of a provider 400. Never clamped silently. |
-| Hosted tool mode on a hop | `native` only with positive `call` evidence taken on the current engine and probe shape, and the user's toggle on; otherwise the gateway proxy (`vibey-hosted-tools.md`). A wrong native declaration is a terminal 400 or a silent drop; the proxy is lossless. So this feature needs positive evidence, unlike efforts. |
-| Native payload replay | only to the same Source, and only while its `replay` evidence is positive and taken on the current engine and probe shape. The decision is made at every request from `HopResolution`; the transcript never stores it. |
+| Effort at request time | Forwarded unchanged (reasoning-intent). A hop with current **negative** evidence for that effort is skipped for this request, as if it were not a candidate. If no candidate remains, the request fails before invocation with `effort_unsupported` naming the effort and the Sources, instead of a provider 400. Never clamped silently. |
+| Hosted tool on a hop | `native: assumed` when the overlay offers the tool for the hop's (Source, model) on an untranslated path with an eligible credential (`runs_on`) and no current negative `call` evidence exists; otherwise `unsupported`, and Vibey declares the same-named function (`vibey-hosted-tools.md` §3.4). A refusal costs one re-rendered request; a silent drop is undetectable and accepted (`vibey-hosted-tools.md` §15). |
+| Native payload replay | `replay: assumed` under the same conditions and no current negative `replay` evidence, only to the Source and identity that minted the payload, on the same origin. Decided at every request from `HopResolution`; the transcript never stores it. |
| Display | §5 |
This fixes #2539 in three places (Phase 1 PR 1b):
@@ -185,10 +196,13 @@ Fields of one vendor entry, mirrored by
| `models[]` | required; ordered, first match wins |
| `match` | exactly one of `prefix` or `id`, non-empty |
| `wire_efforts` | a list of effort names, or `null` (or absent) to defer to models.dev |
-| `hosted_tools` | optional; protocol (`anthropic`, `openai_responses`, `openai_chat`, `google`) → tool (`web_search`, `x_search`, `image_generation`) → `{declaration, price?, include?}`. `declaration` is required, has a `type`, and is sent verbatim. `price` is optional: absent means no list price is known, never zero. OpenAI prices image generation per image token, not per image, so its `image_generation` entry has none. `include` lists Responses `include` values the tool needs (OpenAI web search: `web_search_call.action.sources`). |
-| `price` | `unit` (`call`, `search`, `post`, `profile`), `usd_per_1k` ≥ 0, `as_of` (date) and `url` (https), all required; optional `extra[]` of `{unit, usd_per_1k}`. A per-image unit, whose entries would also carry `quality` and `size`, waits for a vendor that lists a per-image price. |
-- The overlay records what the **provider** offers. Whether a Source (a relay, a subscription) carries it is
- evidence.
+| `hosted_tools` | optional; protocol (`anthropic`, `openai_responses`, `openai_chat`, `google`) → search tool (`web_search`, `x_search`) → `{declaration, price?, include?}`. `declaration` is required, has a `type`, and is sent verbatim. `price` is optional: absent means no list price is known, never zero. `include` lists Responses `include` values the tool needs (OpenAI web search: `web_search_call.action.sources`). v1's OpenAI `image_generation` entry is removed: no chat request declares a hosted image tool (`vibey-hosted-tools.md` §7). |
+| `executor_model` | new, optional, at vendor scope (beside `models[]`): the vendor's lightweight model id that runs proxied search calls on this vendor's Sources (`vibey-hosted-tools.md` §6), e.g. a Haiku, mini or fast tier. The executor call's declaration and `include` are those of the family row that model id matches, on the Source's protocol. A vendor without it is never an executor. |
+| `image_models[]` | new, optional per vendor: `{id, description, endpoint: "images" \| "chat_image", params, price?}`. `description` is the one line the `image_generate` enum shows; `endpoint` says how the gateway runs it (the engine's images endpoints, or the chat route with the image response modality); `params` lists which common parameters the model takes (`size`, `images`, `n`), and `size_forms` which forms of `size` it accepts (`pixels`, `ratio`); `prices[]` is optional, each entry a `price` with an `image` unit keyed by the `size` and `quality` it applies to (absent keys match any), so a vendor that prices sizes or qualities apart is valued at the size the call resolved. `tokens_per_image` is optional: the documented output tokens of one image, which the pricing module values at the model's output token rate as an estimate (shown with ≈) where no per-image price exists. Only models whose route the implementation verified through the shipped engine are listed. |
+| `price` | `unit` (`call`, `search`, `post`, `profile`, `image`), `usd_per_1k` ≥ 0, `as_of` (date) and `url` (https), all required; optional `extra[]` of `{unit, usd_per_1k}`. An `image` unit may carry `quality` and `size` when the vendor prices them apart. |
+- The overlay records what the **provider** offers, and it is the prior every hop starts from: a hosted tool is
+ assumed where the overlay offers it, until a real request refuses it. Whether a Source (a relay, a subscription)
+ actually carries it is learned passively (§3.2).
- An invalid vendor entry disables that entry with a warning; startup never fails. A `providers` value that is not
an object disables the whole overlay. Backend rows never depend on the section.
- The section is read from the bundled file only, never from the remote catalog copy that refreshes backend rows:
@@ -202,16 +216,23 @@ and the existing tone vocabulary (`TimeHint` for dates):
| Evidence | Chip | Example |
| --- | --- | --- |
-| hosted tool, `call` verified | native, with date | "Web search · native · verified 10-13" |
-| hosted tool, no evidence or unsupported, while the tool is enabled | via proxy | "X search · via proxy (xAI API key)" |
-| hosted tool, `call` unsupported | not supported, with basis | "X search · not supported on this Source" |
-| effort unsupported | not supported, with basis | "ultra · not supported on this Source (400, 10-13)" |
-| probe evidence stale by age | re-verify | "Web search · verified 09-02 · re-verify" |
-| hosted-tool evidence from another engine or probe shape | via proxy, re-verify | "Web search · via proxy · engine upgraded · re-verify" |
+| hosted tool, `call` verified (seen in a real response) | normal, with the time | "网页搜索 · 正常 · 10-15" |
+| hosted tool, `call` unsupported | not supported | "X 搜索 · 不支持" |
+| effort unsupported | not supported | "ultra · 不支持" |
- Unknown draws nothing. A healthy unknown is the normal case and must not look like a warning (V6 rule:
exceptions only).
-- Each probe-backed chip has a *Re-verify* action with its cost hint ("about $0.02").
+- A chip opens a detail popover (time, basis, the refusal's HTTP status and code). Every refusal chip's popover has
+ "清除" (owner-approved mockup, 2026-10-15); a hosted-tool refusal clears through the Tools `clear` endpoint
+ (`vibey-hosted-tools.md` §3.3). An effort refusal's popover has its "清除" action, which clears that (Source, model, effort) record, so the next request at that effort tries the
+ Source again (`POST /api/models/sources/<source_id>/evidence/clear` with `{model_id, feature}`, the same verb and
+ shape as the hosted clear). An unknown `source_id` is 404; a missing record is a no-op that answers the Source;
+ `feature` must be `{kind: "effort", name}`, and a hosted-tool feature is 400; the file is written first, and a
+ failed write answers 5xx with nothing changed. A positive chip has no action (`vibey-hosted-tools.md` §8.2). Nothing re-checks: a
+ cleared record comes back only if a real request is refused again.
+- Because refusals no longer expire, the Agent route picker's refused-effort note says where to undo it:
+ "当前没有供应商支持 · 可在模型 → 供应商中清除" / "No Source accepts it now · clear it under Models → Sources"
+ (`chat.picker.effortRefused`, copy only, no action in the picker).
## 6. Pricing
@@ -262,23 +283,20 @@ and the existing tone vocabulary (`TimeHint` for dates):
### 6.4 What hosted tools need from pricing
-1. **A per-call cost hint** in Models (the Tools tab and the probe confirm) and on the use-time card:
- - native: the tool fee per call plus a token estimate;
- - proxy: the same plus the executor model's call.
+1. **A per-call price** on the Tools tab (the overlay's list price per tool) and the real cost on the use-time card:
+ - native: the tool fee plus the response's tokens;
+ - proxy: the executor's lightweight-model call plus the tool fee;
+ - `image_generate`: the image model's per-image price where listed, else its reported usage at its token rate.
- Before a probe runs, the Tools read states each candidate's `probe_estimate`: one call probe priced from its
- nominal usage (`hosted_probe.ESTIMATED_USAGE` and one search's counters), `included` on a monthly Source, and
- unknown rather than zero when the model has no token price.
-
- All of it is computed by the one pricing owner, `pricing.py` (`hosted_response_cost`, reached through
+ There is no estimate before a call: nothing runs before the model calls a tool. All of it is computed by the one pricing owner, `pricing.py` (`hosted_response_cost`, reached through
`ModelHubService.hosted_call_cost`, which reads only the price table the usage writer already holds, so pricing a
response does no I/O). It is stored once per response: as the message's
`hosted_summary.cost` for native calls, and as `ProxyExecution.cost` for a proxied call, which is its own executor
response. A provider-reported figure is never copied into individual calls. Neither the
executor nor an adapter prices anything itself.
-2. **Executor choice.** The Tools tab lists the verified executor candidates with their cost hints and billing mode.
- The user picks one; the default is the first verified candidate in Vibey's Source order. Avibe does not
- auto-optimize cost in Phase 1, because relay prices are unknowable.
+2. **Executor choice is automatic.** The chain is the Sources whose vendor offers the tool, in the user's optional
+ executor order, then Vibey's Source order, each on its vendor's lightweight model (`vibey-hosted-tools.md` §6).
+ Avibe does not auto-optimize cost, because relay prices are unknowable.
3. **Usage accounting.** The proxy executor's calls are metered like any gateway call (usage ledger, provenance),
attributed to the executor Source.
@@ -299,10 +317,10 @@ No new billing store, budget, or cap.
1. A fact from models.dev or the overlay never blocks a request or removes a tier on its own. Only evidence does.
2. Only a narrow rule creates negative evidence. The rule names the (Source, model, feature) it learned. A generic
error creates none.
-3. No probe runs without a user action, and every probe action shows its cost before it runs.
-4. Changing a Source's identity drops its evidence. An engine upgrade that changes `hosted_wire` marks probe
- evidence stale; it does not delete it. Stale hosted-tool evidence from another engine or probe shape never authorizes native mode or native
- replay.
+3. Nothing probes. Every evidence record comes from a real request in a turn the user started.
+4. Changing a Source's identity drops its evidence. Negative evidence, for efforts and hosted tools alike, has no time
+ limit: it reads as unknown once its wire stamp differs from the current one or the user clears it. Positive
+ evidence never changes routing.
5. #2539: a Source that rejected `ultra` shows "ultra · not supported on this Source". The next request at `ultra`
either skips that hop or fails before invocation with `effort_unsupported`, never a provider 400.
6. Valuation applies context tiers when a call's input tokens exceed the tier size. A model with tiers and no flat
diff --git a/docs/plans/vibey-hosted-tools.md b/docs/plans/vibey-hosted-tools.md
index 0e4cbd821..34846142a 100644
--- a/docs/plans/vibey-hosted-tools.md
+++ b/docs/plans/vibey-hosted-tools.md
@@ -1,46 +1,66 @@
# Vibey hosted tools
-Status: **design**, 2026-10-13, for owner review.
+Status: **design v2**, 2026-10-15, owner-approved direction (passive, default-on, simpler). It replaces design v1
+(2026-10-13), whose active-check model the owner rejected after looking at rc4's Tools tab.
- Scope: Vibey only. Claude Code, Codex and OpenCode are unchanged, and there is no CLI.
-- Foundation: [`model-hub-capability-model.md`](model-hub-capability-model.md), which covers evidence, the overlay and
+- Foundation: [`model-hub-capability-model.md`](model-hub-capability-model.md), which covers priors, evidence and
pricing.
- Evidence: the runtime spike of 2026-10-13 (40 + 10 upstream calls through the local engine on API-key relay
Sources). Its tables are summarised where a rule depends on them.
+- What is already built (rc4) and what v2 removes or changes is listed in §11; the implementation split is §12.
## 0. Owner decisions this design implements
-- **Native first.** A provider's hosted tool is used natively when the current route is verified for it. Otherwise
- Vibey offers a gateway-executed **proxy** tool with the **same name and schema**.
-- **The gateway owns** the catalog, verification, the user toggles in Models, the proxy executor, and per-hop
- selection and filtering. Filtering means a pinned request is refused, never rewritten (§3.5).
-- **The transcript stays portable.** Each hosted call keeps a canonical record, plus the origin-tagged native payload.
- The payload is replayed only to the same verified origin.
-- **Phases.** Phase 1 is web search, X search and image generation (owner decision, 2026-10-13 19:10). There is no
- Phase 2.
+- **No active detection.** Nothing calls a provider to find out whether a tool works: no user-started check, no
+ check-all, no background probe. "Check all" would have probed hundreds of (Source, model) pairs: a large bill,
+ rate limits and possibly provider risk control. Users never need to understand Source × model × tool.
+- **One switch per tool, on by default.** The cost and privacy consequences are stated plainly in the public docs
+ (§9), not in onboarding.
+- **Assume from rules, call blind, learn passively.** A route is assumed to support a tool when its vendor offers it
+ (§3.1). Real use teaches the rest: a real response that carries the tool's item is positive evidence, and a real
+ error that names the tool is negative evidence (§3.2).
+- **Show what real use learned.** The UI shows the last real execution and any refusal, never a guess (§8).
+- **The agent decides what to declare; Model Hub supplies facts.** Model Hub states per hop and tool what the
+ priors and evidence say. Vibey decides each request's declarations, and re-renders when the gateway reports a
+ refusal (§3.5).
+- **Image generation is one direct tool.** `image_generate` names its model explicitly and runs on the provider's
+ image endpoint, never as a hosted declaration on a chat request (§7).
+- **Pre-release state is not migrated.** 3.2.0 stable has no hosted tools. rc-era probe evidence is pruned,
+ and an rc-era `hosted_tools` section's unknown keys and fields are ignored, with no compatibility code (owner
+ directive).
## 1. Example
-The user enables X search in Models. Vibey is on Claude Opus through an Anthropic API key. An xAI API key is
-verified for X search.
-
-1. Anthropic has no X search, so Vibey's request declares `x_search` as an ordinary function with the canonical
- schema (§2).
-2. Claude calls `x_search({"query": "from:OpenAI within_time:7d"})`. Vibey runs it through the gateway's proxy
- executor, which sends one short native request to the xAI Source and returns numbered posts with links and
- excerpts.
-3. The tool card shows the query, "via proxy · xAI API key", and the cost reported by xAI. The answer's citations
- render as links.
-4. Next turn the user switches Vibey to Grok on the xAI Source. That hop is verified for X search, so `x_search` is
- declared natively.
-5. The earlier proxied call is an ordinary tool call and result, so it replays to Grok unchanged.
+The user has an Anthropic API key, an xAI API key and an OpenAI API key, and has changed no tool setting.
+
+1. Vibey runs on Claude Opus through the Anthropic key. Anthropic offers web search on the `anthropic` protocol, and
+ nothing says this Source refuses it, so `web_search` is declared natively. X search is not offered by Anthropic,
+ so `x_search` is declared as an ordinary function with the canonical schema (§2).
+2. Claude calls `x_search({"query": "from:OpenAI within_time:7d"})`. Vibey's tool runtime sends it to the gateway's
+ executor. The gateway builds the executor chain for X search (§6): the xAI key is the only Source whose vendor
+ offers it. It sends one short request to xAI's lightweight model with X search forced, and returns numbered
+ posts with links and excerpts.
+3. The tool card shows the query, "via xAI API key" with xAI's lightweight model, and the cost xAI reported. Models → Tools now
+ says "X 搜索 · 最近一次由 xAI API key 执行 · 正常 · 10-15 14:02".
+4. Claude then asks for a picture. It calls `image_generate({"model": "gpt-image-2", "prompt": "…"})`. The gateway
+ sends the prompt to the OpenAI key's image endpoint, Vibey saves the image as a file, and the model receives the
+ text path record (§7.3). The card shows the image and "gpt-image-2 · OpenAI API key".
+5. Next turn the user switches Vibey to a relay Source that declares itself `openai` but refuses web search with
+ `400 Unsupported tool type: web_search`. The gateway records that refusal for the relay (§3.2) and answers the
+ pinned request `pin_unavailable` with the reason. Vibey's loop re-resolves the hop, which now says the relay does
+ not run web search natively, and resends with the `web_search` function instead (§3.5). Models → Tools shows
+ "网页搜索 · relay 不支持,已改用 Anthropic API key".
## 2. Concepts
-- **One user-facing tool per capability.** Phase 1 has `web_search`, `x_search` and `image_generation`.
-- **Two execution modes behind one name and schema.**
- - **Native:** the provider's hosted declaration on the wire. The provider runs the search.
- - **Proxy:** a function with the canonical schema. Vibey's tool runtime asks the gateway's executor to run it.
-- **The canonical schema is the providers' trained interface.**
+- **One user-facing tool per capability.** `web_search`, `x_search` and `image_generate`.
+- **Two execution modes for the search tools, one name and schema.**
+ - **Native:** the provider's hosted declaration on the wire. The provider runs the search inside the model call.
+ - **Proxy:** a function with the canonical schema. Vibey's tool runtime asks the gateway's executor to run it on
+ another Source (§6).
+- **`image_generate` has one mode: direct.** It is always a function, and the gateway calls an image endpoint. The
+ model chooses the image model through the `model` argument (§7).
+- **The canonical search schemas are the providers' trained interface.**
- `web_search` is `{"query": string}`, and only that. Anthropic's `server_tool_use.input` is exactly `{query}`.
OpenAI's and xAI's `web_search_call.action` carries `query` for `type: "search"`.
- The other knobs are declaration configuration, not per-call arguments: OpenAI's `open_page`/`find_in_page`
@@ -54,246 +74,279 @@ verified for X search.
when the target also declared the native tool under that name. Anthropic accepted a client `tool_use` named
`web_search` next to `web_search_20250305`, and Responses accepted a `function_call` named `web_search` next to
`{"type": "web_search"}`.
-- `image_generation` is `{"prompt": string, "size"?: string}` (§7). That is the argument surface of OpenAI's
- image tool calls; `quality` and `background` are declaration configuration.
-
-## 3. Gateway responsibilities
-
-### 3.1 Catalog
-
-- **The catalog is the overlay's `providers` section** (capability model §4): for each provider model family and
- protocol, the native declaration and the list price.
-- **What it lets the gateway answer, without a network call:**
- - which tools exist;
- - which Sources might run each one natively;
- - what a call costs.
-
-### 3.2 Verification
-
-- **Live probes are the only way to `verified`.** They run on an explicit user action (capability model §3.3).
-- **A probe is the production request.** It is built by the same Vibey request builder and with the same native
- declaration as a real turn on that (Source, model). Two things differ:
- - the transcript, which is one fixed user message;
- - for the `call` probe, `tool_choice` forcing the hosted tool, where the protocol allows it.
-
- So a probe cannot pass or fail for a shape that production never sends.
-- **A probe has its own resolution.** Normal resolution gives native mode only after `call: verified` (§3.5), so a
- first verification could never send a native declaration. Model Hub therefore builds a probe resolution, and only
- for the user's probe action. It names the probed (Source, model) and carries the overlay's native declaration
- whatever the current evidence, with the endpoint built as the Vibey launch builds it (the Source's vendor as its
- provider). Vibey's adapter runs unchanged, and Model Hub serves every request it sends with its own invocation
- of exactly that Source, never the turn gateway, so there is no route and no failover. A resend the adapter makes
- for a field the endpoint refused before answering (Anthropic's one-hour cache lifetime) is one more such call;
- each probe step (call, then replay) sends at most two requests and runs the model once. A result is recognized only
- as the hosted call a real turn would keep. Normal turns never receive a probe resolution.
-- **The `call` probe.** The fixed message is "search the web for a news article published today about technology and
- reply with its URL" (X search: "search X for posts about 'Avibe local-first agent OS' and reply with the first
- post's URL"). The web search asks for fresh articles because the replay probe asks about the other results: a
- fixed topic's other results (its site's other pages) can be inferred from the first, while a page published after
- the model was trained cannot, and a post's URL carries its id.
- - **`verified`:** the response completes and carries the provider's own result item for that tool (§4.2).
- - **`unsupported`:** only an HTTP 400 that names the tool type (observed: `Unsupported tool type: x_search`).
- - **Inconclusive, not evidence:** a completed response without that item. The model may simply not have used the
- tool, which looks the same as a silent drop. The UI says "the model didn't use the tool; try again".
- - Silent drops happen on translated paths, as observed with `image_generation` on an Anthropic route. Those
- paths are never native anyway (§3.5).
- - **Not evidence:** a transient failure (overload, 5xx, timeout). The UI reports "couldn't verify, try again"
- (observed: every OpenAI-relay web search ended with an in-stream "servers overloaded").
-- **One action, both aspects.** `POST /api/models/hosted-tools/<tool>/probe` runs the `call` probe. When it
- verifies and is recorded, and the tool has a `replay` aspect on a protocol that replays natively, the `replay`
- probe follows at once, on the call's own turn. The `image_generation` call probe reads the image through Vibey's own
- parsing, which keeps it only when it is an image; the probe keeps no file. The Tools tab's estimate covers both
- requests.
-- **The `replay` probe.** A second production request with the native declaration still present. Its history is
- the call probe's turn, with the native payload verbatim and without the answer's reasoning (which may restate the
- results, readably or encrypted), followed by "list the URLs of the other results you
- found, without using any tool again", under instructions that ask for an answer from those results without a
- tool (the call's would ask for the tool). Nothing is forced.
- - **`verified`:** the answer names a result URL the call returned that its visible answer does not show (only the
- replayed payload holds it), and the response makes no new call to the tool.
- - **`unsupported`:** a 400 that names the replayed hosted content (observed on the Anthropic relay, 3 of 3:
- `Invalid encrypted_content in search_result block`), or a new call to the tool (§12 item 23). Transport
- acceptance alone is never verification. xAI accepted verbatim replay, 3 of 3.
- - **Inconclusive:** an answer naming no such URL, or a refusal, and any request that did not carry the native
- payload verbatim. With no hidden URL to ask about, no replay runs.
- - **Matching:** a result's URL is matched exactly but for the equivalences RFC 3986 allows (the case of its scheme
- and host, an empty path as `/`); only where prose ends a written URL is read both ways.
- - **Known by design:** a result that is a section or home page can still be guessed by a model whose payload was
- dropped. The fresh-article query makes such results rare, and a re-probe replaces a wrong record.
- - **Within the UI's wait:** the whole probe answers inside the UI's RPC timeout. Each call's deadline is the
- tool's (as for a turn's proxied call) or what the probe has left, whichever is shorter. A replay with under a
- minute left is not sent and reads as transient: try again.
-- **Cost and when probes run.** A probe pair costs about $0.02–0.15 (spike: xAI $0.01–0.11 per call, Anthropic $0.01
- per search plus tokens). The Tools tab shows the estimate before running.
-- **What changes probe results** (capability model §3.3). A Source identity change drops them. A change of the engine
- manifest's `hosted_wire` (an engine upgrade whose hosted passthrough is not byte-identical) or a probe-shape change
- makes them **current-wire stale**: they no longer describe the request being sent, so for
- routing they count as unknown (proxy and synthetic replay) until the user re-verifies. Age alone (30 days) only
- marks them for re-verification and keeps routing.
-- **Failures in real use demote evidence** through the narrow rules in capability model §3.2.
-- **Relation to #2539.** It is the same class (a prior taken as a Source fact), solved by the same evidence store.
- Efforts need only negative evidence. Native hosted tools need positive evidence, because their failure is terminal
- or silent while the proxy is lossless.
-
-### 3.3 User toggles
-
-- **Placement.** One **Tools** tab in Models, next to Sources, Quota, Usage and Logs (§6).
-- **Each tool is off by default** (§6.3).
-- **What a toggle stores.** A new optional V2 config section, owned by the Model Hub API and written only through
- it:
+- **Three facts per hop and search tool** (§3.4), all derived by Model Hub, none chosen by the user:
+ - `native`: `assumed` (the vendor offers it and nothing says this Source refuses it) or `unsupported` (negative
+ evidence);
+ - `replay`: `assumed` or `unsupported`, the same way, for sending a native payload back to its Source;
+ - the executor chain is not a hop fact: the gateway resolves it when a proxy call arrives (§6).
+- **Evidence is passive** (§3.2). It is written only from real traffic, by the gateway's one evidence owner.
+
+## 3. Model Hub and gateway responsibilities
+
+### 3.1 Priors: what each vendor offers
+
+- **The catalog is the overlay's `providers` section** (capability model §4), bundled with the code that sends its
+ declarations. For each vendor and model family, per protocol, it holds:
+ - the native declaration of each search tool the vendor offers, with its `include` values and list price;
+ - new, at vendor scope: `executor_model`, the vendor's lightweight model that runs proxied search calls (§6), e.g.
+ Anthropic's Haiku tier, OpenAI's mini tier, xAI's fast tier; the executor call uses the declaration of the family
+ row that model matches. The implementation PR picks the shipped ids;
+ - new: `image_models`, the vendor's image models with a one-line description, the endpoint kind (§7.4), the
+ parameters each supports, and a list price where one exists.
+- **What priors decide.** Which tools a hop may declare natively, which Sources can run a proxied search, and which
+ image models the user can pick. Priors are never an allowlist for anything a user sends: a vendor without a row
+ simply gets the proxy function.
+- **Eligibility is unchanged.** `runs_on` stays the one rule: a hub Source with an eligible credential and an
+ untranslated path that serves the model (an API-key Source any model it does not list as retired; a subscription
+ only its listed models), for which the overlay declares the tool. A Claude subscription Source is never eligible:
+ not for native mode, not as an executor, not for images. Anthropic restricts OAuth credentials to Claude Code and
+ its own apps ([`model-hub-tos-review.md`](model-hub-tos-review.md)).
+- **Translated paths are never native.** The engine coerces web search across protocols and it worked in the spike,
+ but its result shapes are hybrids (Anthropic `web_search_result_location` citations inside a Responses message),
+ so they are not a contract.
+
+### 3.2 Passive evidence
+
+The evidence store, its record and its owner are the capability model's §3. v2 changes what writes it:
+
+- **No probes.** `basis: probe` no longer exists. Every record is `basis: observed`, written by the gateway's
+ classifier (`evidence_rules.py`) from a real request, and only for the exact (Source, model, feature) it names.
+- **Positive (`verified`, display only).** A served response that carries the provider's own completed item for a
+ tool the request declared natively: Responses `web_search_call` with `status: completed`, or a `custom_tool_call`
+ named `x_keyword_search`, `x_semantic_search`, `x_user_search` or `x_thread_fetch`; Anthropic `server_tool_use`
+ named `web_search` with a `web_search_tool_result` whose `content` is a result list, not the error object
+ (`web_search_tool_result_error`), which arrives under the same block type. A proxy executor call is itself a native call on the executor Source, so it writes the
+ same record for the executor's (Source, model). A successful `image_generate` writes it for (Source, image model).
+ - **Where the gateway sees it.** The served-stream observer (`ProtocolSSEState` / `ProtocolFactProjector`) keeps
+ only bounded scalar projections today, and no item types. It gains projection paths: Responses
+ `response.output_item.done` → `item.type`, `item.name`, `item.status`, and the buffered `output[*].type` and
+ `output[*].name` and `output[*].status`; Anthropic `content_block_start.content_block.type`, `.name` and
+ `.content.type`. Buffered responses take the same paths through `observe_buffered_protocol_response`.
+ - **Bounded writes, off the response path.** Each write rewrites the evidence file, so a positive record is written
+ at settlement, off the loop, after the response completes, and only when there is no record or the existing
+ positive record is older than one hour, never on every response. **A positive write never replaces a negative
+ record:** a success that settles after a concurrent refusal must not re-enable native routing, so only a clear
+ or a stamp change removes a refusal. It is keyed on
+ the serving Source's identity from the final admission snapshot.
+ - `resolve()` reads a record by its `status`, no longer by its `basis`: today it reads every `observed` record as
+ a refusal.
+ - **A positive record carries the observed `mode`** (`native`, `executor` or `direct`) and is never retired by the
+ wire stamp: it is display-only history, so an upgrade does not hide it. The stamp retires `unsupported` records
+ only. A positive and a negative record for the same (Source, model, feature) coexist (the store keys by status
+ too), so a later refusal never erases the success history the projection is seeded from after a restart.
+ - **The latest execution is a projection, not a file write.** Model Hub keeps, per tool, the latest success
+ (`{source_id, model_id, mode, at}`) in memory, updated on every success and seeded at startup from the persisted
+ positive records. The read's `latest_ok` comes from it, so the status line is current even while file writes are
+ throttled.
+ - Positive evidence never changes routing. It feeds the "最近一次 … 正常" lines (§8) and nothing else.
+ - A `google` hop has no native hosted tools, and the Chat route Vibey uses gives no hosted item to observe.
+- **Negative (`unsupported`) is routing state.** When the file write fails, the narrow rule still updates the
+ in-memory store and logs the loss, so the re-resolve that follows (§3.5) cannot declare the refused tool natively
+ again. The narrow rules of #2551 fire on a real error before output, unchanged in form:
+ - `Unsupported tool type: <type>` for a declared type → hosted tool `call`;
+ - `Invalid encrypted_content in search_result block` while the request replays a web-search result → `web_search`
+ `replay`;
+ - **new:** an upstream image endpoint that refuses the model or the endpoint before producing anything (a 404, or a
+ 400 naming the model or endpoint as unsupported, as a relay without the vendor's image endpoint answers) →
+ `image_generate` `call` for that (Source, model); a refusal of the endpoint itself (the path is not served) is
+ written for every image model the overlay lists for that Source on that endpoint kind, so sibling models do not
+ each fail once. Only an upstream refusal counts: the images path goes through
+ `_is_local_model_registration_failure`, and the engine's own refusals never teach, neither CPA's "only supported
+ on /v1/images/generations and /v1/images/edits" nor a route 404 that Avibe's own engine config caused. The record
+ is stamped and retired by the wire stamp like any negative. The enum drops that pair from the next turn (§7.2), and the refusal shows and
+ clears on the image card like a search refusal (§8.1);
+ - **new:** xAI's plain-text refusal of a replayed payload, `Could not decrypt the provided encrypted_content`,
+ which carries no code. It does not say which ciphertext failed, and a stale or foreign blob draws it as well as
+ an unsupported replay, so it writes no evidence unless the Vibey lane's xAI A/B shows that xAI refuses fresh
+ ciphertext from the same account. The gateway does not classify it: it is no failover-class failure and no narrow
+ rule fires, so it passes through as the provider's 400 on pinned and unpinned requests alike, and Vibey's adapter
+ is its one classifier (§3.5). If the A/B makes it evidence, it becomes a narrow rule here and its pinned case a
+ `hosted_unsupported` reason.
+ - Generic errors never create evidence: 5xx, overload, rate limit, auth, and any 400 that does not name the
+ feature.
+- **Lifetime of negative evidence (owner decision, 2026-10-15 01:20).** Negative evidence, for hosted tools and
+ efforts alike (capability model §3.2), has no time limit. It stays until
+ one of these clears it:
+ - the user clears it in Models → Tools, for one (Source, tool) or for every Source of a tool (§8.1);
+ - its wire stamp no longer matches, which happens on its own when the Source's config or the engine release
+ changes.
+
+ Every record carries the wire stamp it was observed under, the engine release, the Avibe release (which covers
+ the bundled overlay's declarations and the adapters' request shape), and a digest of the Source's rendered engine
+ entry (credentials and the model list excluded), and a record whose stamp differs from the current one reads as
+ unknown. The stamp is computed when the engine config is rendered (`sync_sources`) and
+ held in memory per Source; evidence reads and writes take it from memory and never render on a request path, as
+ `engine_stamp()` is never called on one. So a refusal learned under one engine or one rendered config cannot survive a
+ change that could reverse it, such as the dependency lane's `is-compat` flip for xAI (#2620), which changes what
+ xAI receives for replayed reasoning. A change on the provider's side that the stamp cannot see (a relay that starts
+ supporting a tool) waits for the user's clear. A Source identity change drops the Source's evidence as before.
+- **What v1's staleness rules become.** v1 needed `engine` and `shape` to stop positive probe evidence from vouching
+ for a wire it was not taken on. v2 routing never reads positive evidence, so `shape` and probe staleness go
+ (§11). The wire stamp keeps one job: retiring negative evidence. The `hosted_wire` manifest field is not
+ introduced, so `engine_stamp()`'s `hosted_wire` branch (#2623) is removed.
+
+### 3.3 User settings
+
+- **Placement.** Models → Tools, grouped by capability (§8).
+- **What the settings store.** The optional V2 section `model_hub.hosted_tools`, owned by the Model Hub API and
+ written only through it:
```json
"model_hub": {
"hosted_tools": {
- "web_search": {"enabled": true, "executor": {"source_id": "src_…", "model_id": "grok-4.6"}},
- "x_search": {"enabled": false, "executor": null}
+ "web_search": {"enabled": true},
+ "x_search": {"enabled": false, "executor_order": ["src_…", "src_…"]},
+ "image_generate": {"enabled": true, "default_model": {"source_id": "src_…", "model_id": "gpt-image-2"}}
}
}
```
- - Fields, keyed by catalog tool name (`web_search`, `x_search`, `image_generation`):
-
- | Field | Rule |
- | --- | --- |
- | `enabled` | boolean, required |
- | `executor` | required: `null`, or `{source_id, model_id}` with both non-empty |
- - The section is absent on every released config, and absence means every tool is off. No migration is needed:
- `ModelHubConfig`'s loader accepts the new optional section. An unknown tool key disables that entry and logs a
- warning (safe degradation); it never fails startup.
- - An executor whose Source or model no longer exists reads as `null`.
- - It stores no per-Agent copy: Vibey reads it through hop resolution.
-
-### 3.4 Proxy executor
-
-- **Endpoint:** `POST /vibey/v1/hosted-tools/{tool}` on the gateway, authenticated with the turn's gateway token.
- The body is the canonical arguments and the turn's executor binding (§3.4).
-- **Executor choice, bound per turn.**
- - Hop resolution picks the executor and returns it in `HopResolution.hosted_tools[tool].executor` (§3.5), for
- every enabled tool and in either mode. The pick is the configured executor if it has `call: verified`, otherwise
- the first verified (Source, model) in Vibey's Source order.
- - The proxy call sends that binding with the turn token, and the gateway runs that executor and no other.
- - A config change (another executor, a disabled tool, a removed Source) applies from the next turn, as every
- runtime config change does (AGENTS.md).
- - The binding is held for the turn. Ordinary edits to the executor's Source (models, order, name) apply from the
- next turn. Only removing or disabling that Source, which takes it off every hop at once, makes a bound call
- return a tool error. The call never silently switches Source or billing.
- - **Only an eligible credential.** A Claude subscription Source is never eligible: not as executor, not for a
- probe, and not for native mode (§3.5). Anthropic restricts OAuth credentials to Claude Code and its own apps
- ([`model-hub-tos-review.md`](model-hub-tos-review.md)).
- - If no executor is verified, the call returns a tool error naming the fix ("verify X search on a Source in
- Models"). Vibey shows it like any tool error. A call that never reached an executor has a `failed` record and no
- `execution` (§4.2).
-- **The request depends on the tool.** For a search tool, it is one short native call with the tool forced, a fixed
- instruction to search and list results, and a small output cap. For `image_generation`, it is one call with the
- tool forced that renders the supplied `prompt` at the supplied `size` (§7.2).
- - It sends **no reasoning effort**. The executor (Source, model) is verified for the tool, not for any effort, and
- an unverified effort could fail a verified tool.
-- **The result is the canonical record only:**
- - the `HostedRecord`, with the action, `status`, `error` and `sources[]` (`url`, `title`, and, where available,
- `snippet` and `page_age`).
- - A proxied call is exactly one executor response. So when the provider returns no per-call results (xAI X
- search), the record's `sources` are that response's cited posts. A native response with several calls keeps
- those in `hosted_summary` instead (§4.2).
- - Either way the calling model gets numbered posts with links and excerpts;
- - the `ProxyExecution`, when an executor ran: executor origin, Source, billing mode, and the call's cost. A
- proxied call is a whole executor response, so its cost is per call.
- - The executor does not write model-facing text. Vibey's tool runtime renders the tool result from the record with
- the **same function** that renders a synthetic replay (§5), so the text a model sees for a proxied call and for a
- replayed native call never diverge.
- - Excerpts are what make a result reusable. A model shown URLs alone treated the earlier answer as unsupported and
- said so; a model shown titles and snippets answered the follow-up without searching again.
- - OpenAI and xAI return no page text, so the executor's instruction asks for a one-to-two-sentence excerpt per
- result, stored as `snippet`. Anthropic supplies `cited_text`.
-- **Cost and latency.**
- - Cost is one model call plus the tool fee: xAI about $0.01–0.11 per call; Anthropic $0.01 per search plus tokens.
- It is metered on the executor Source (usage ledger, provenance) and shown on the card.
- - Money is computed by one owner, Model Hub's pricing module (capability model §6), for both proxied and native
- calls. Neither the executor nor a Vibey adapter prices anything itself.
- - Measured latency is 7 s (Anthropic) and 35–61 s (xAI at high effort). The executor's own latency is an acceptance
- measurement, not a promise.
-
-### 3.5 Per-hop selection and failover
-
-- **Hop resolution.** C-6 `HopResolution` gains `hosted_tools`. For each enabled tool it gives:
- - the primary hop's `mode` (`native` | `proxy`);
- - for `native`, the wire declaration;
- - the executor bound for this turn, `{source_id, model_id}` or `null` when none is verified (§3.4). It is present
- for **every** enabled tool, whatever the mode, because a native request that comes back `pin_unavailable` is
- re-rendered with the proxy function within the same turn;
- - `replay`, the **current** `replay` evidence for the primary hop's Source and model.
-
- `native` requires all of these:
- - the toggle on;
- - an eligible credential (§3.4);
- - `call: verified` for that (Source, model), taken on the current engine and probe shape (§3.2);
- - an untranslated path.
-
- `replay` is likewise true only for `replay: verified` evidence taken on the current engine and shape.
-
- Vibey builds the request from these fields (§4.1, §5).
-- **One owner for every conversion: Vibey.** Vibey renders every request from its canonical records. The gateway
- never rewrites hosted content: no declaration swap and no history conversion. It sees only wire bytes, and the
- canonical record (for xAI X search, the response's citations) is not in them.
-- **Pinned requests.** A request that carries Source-specific hosted content carries the gateway request header
- `x-avibe-pin-source: <source_id>`. Source-specific hosted content means:
- - a native declaration;
- - a `native.payload`;
- - an in-flight continuation (§4.3, §4.4).
-
- The value is `HopResolution.source_id` for the first two. For a continuation it is the Source the previous
- response came from, according to the served-hop report.
-
- **As implemented (orchestrator decision, 2026-10-14):** every model attempt resolves a fresh hop (C-6 item 3), so
- verbatim content goes only to the hop whose own Source served it, on the same origin, and every pin is
- `HopResolution.source_id`. A continuation whose fresh hop is another Source takes the in-place text form (§4.4),
- unpinned. Pinning it to the previous Source would build the request for one hop (declarations, model, efforts,
- signature target) and serve it from another. A continuation also sends `x-avibe-pin-model` with its served model
- when that id is ASCII. Without the header, the gateway takes the pinned Source's own model, which is the same hop.
- - The gateway serves a pinned request only from that Source, with no failover and no recovery wait.
- - The gateway answers the local error `pin_unavailable` in three cases:
- - the Source cannot be admitted for this content, checked before invoking anything: it is cooling down, it was
- removed, it has no route, or its evidence for a declared native tool or replayed payload is no longer
- positive;
- - its attempt ends before model output with a failure that normal routing would fail over from;
- - its attempt ends before model output with an error that a narrow hosted-content rule names (capability model
- §3.2). That rule also records the negative evidence.
-
- In the last two cases `pin_unavailable` replaces the failover. The answer is HTTP 409 with
- `{"type": "error", "error": {"type": "model_hub_pin_unavailable", "code": "pin_unavailable"}}` and is never
- shown to the user. Any other error passes through as today.
- - Vibey then re-renders that same request in **portable form** and sends it unpinned. Portable form means:
- proxy declarations, synthetic history (§5), and the in-place text form for in-flight content (§4.4).
- - An unpinned request fails over exactly as today.
- - The cost is one local round trip on failover for a request with native content. The upstream is not called
- again for nothing: a failure before output is a failover attempt either way.
-- **Consequence:** a hop never receives a hosted tool or hosted payload it has no positive evidence for. Two
- observed failures become unreachable: `x_search` → OpenAI (`400 Unsupported tool type`) and `image_generation` →
- Anthropic (silently dropped).
-- **Not changed here:** C-6 item 6. The gateway still strips opaque thinking payload at failover for unpinned
- requests, which is a second owner of that conversion. Hosted content no longer depends on it; unifying it is a
- separate decision.
-- **Translated paths are never native.** The engine coerces web search across protocols and it worked in the spike,
- but its result shapes are hybrids (Anthropic `web_search_result_location` citations inside a Responses message),
- so they are not a verified contract.
+ | Field | Rule |
+ | --- | --- |
+ | `enabled` | boolean; absent means **on** |
+ | `executor_order` | search tools only, optional: Source ids in the order the user wants executors tried. Absent means fully automatic (§6). Ids that no longer name a Source are skipped. |
+ | `default_model` | `image_generate` only, optional: `{source_id, model_id}`. Absent, or naming a model no longer available, means the first available model in catalog order (§7.2). |
+
+ - **Absence means on.** The section is absent on every released config, so an upgrade from 3.2.0 turns every
+ tool on (owner decision, §0). A tool key the loader does not know is ignored with a warning.
+ - The loader ignores, with a warning, an unknown tool key and an unknown field inside an entry, and keeps the
+ fields it knows. So an rc-era section keeps each tool's `enabled`, and a user's explicit opt-out survives the
+ upgrade; its `image_generation` key and v1's `executor` field are ignored. This is one generic loader rule, not
+ rc-specific code.
+ - A settings change applies from the next turn, as every runtime config change does.
+- **API.** Saved and effective values are separate fields, and the UI never writes back an effective value: v1's
+ toggle echoed the resolved executor and so froze "automatic" into a saved choice.
+ - `GET /api/models/hosted-tools` → `{hosted_tools: HostedToolsStatus}` (§10.3). Per tool:
+ - `enabled`;
+ - `status: {latest_ok, refused[]}` (§8.1): `latest_ok` is `{source_id, model_id, mode: "native" | "executor" |
+ "direct", at}` or null (`direct` for an image call), the latest positive record; `refused[]` is `[{source_id, model_id, aspect, at, reason}]`, the
+ current negative records, with `aspect` `call` or `replay` and `reason` the record's detail (HTTP status and
+ upstream machine code, never provider prose); `verified[]` is `[{source_id, model_id, mode, at}]`, the persisted
+ positive records, one per pair, from which the Source chips derive (hosted evidence lives on this read, which
+ the clears answer; the Source read keeps effort evidence);
+ - `latest_ok` is the in-memory latest-execution projection (§3.2), not the newest file record;
+ - search tools: `executor_order` (saved, null when automatic), `effective_order` (as the gateway would try now),
+ and `executor_candidates: [{source_id, billing, relay, price}]` in effective order (`relay` true for a Source on a
+ non-official endpoint, labelled "at API price"), every eligible executor Source (a Claude
+ subscription never is) with its per-call price, so the order can be edited over the full list;
+ - `image_generate`: `default_model` (saved, null when default; a saved model no longer available, or whose pair
+ is refused, stays saved, flagged `available: false`); `effective_default` (the saved default if available,
+ else the same `model_id` on another Source that serves it, since the user picked a model, not a relay, else
+ the first available model in catalog order); `models: [{source_id, model_id, description, price}]`, where
+ `price` is `{usd, basis: "list" | "estimated"}` per image or null ("暂无单价"), exactly
+ the enum's candidate pairs, so a refused pair leaves it and the card's refusal line says why (clearing the
+ refusal brings the pair back, and a saved default with it, with no write); and `image_offered_by: [vendor]`,
+ the vendors whose overlay lists image models, for the empty state.
+ - `PUT /api/models/hosted-tools/<tool>` is per field: an absent field is unchanged, and an explicit `null` resets
+ `executor_order` to automatic or `default_model` to the default. `enabled` is a boolean. It answers the same
+ read.
+ - `POST /api/models/hosted-tools/<tool>/clear` with `{source_id, model_id?}` clears that Source's negative records
+ for the tool (`call` and `replay`): for that model when `model_id` is given (a Source chip on a model row), else
+ for every model (the Tools tab's per-Source line); with `{}` it clears them for every Source of the tool. A
+ `model_id` with no records is a no-op like the others. It answers the same
+ read, writes nothing else, and from the next request (hop facts are resolved per request, §3.4) the tool is
+ assumed again on those Sources. A request in a running turn may therefore try it again; if it still refuses, the
+ re-resolve bounds of §3.5 apply.
+ - An unknown tool is 404, as for the PUT. A `source_id` that names no Source, or a Source with no records, is a
+ no-op that answers the read, so a double click, two tabs or a Source removed meanwhile all succeed. Any other
+ body is 400.
+ - **A clear persists before it takes effect.** It writes the evidence file first and then memory; if the write
+ fails it answers 5xx and changes nothing, so what the UI shows is true after a restart too. (A refusal is the
+ reverse: it updates memory even when its write fails, because it is routing safety, §3.2.)
+ - The UI sends clears through the same serialized write queue as the PUT.
+ - The probe endpoint is removed (§11).
+
+### 3.4 Hop facts
+
+- **C-6 `HopResolution.hosted_tools`** gives, for each enabled search tool, the primary hop's facts:
+ - `native`: `assumed` or `unsupported`;
+ - `declaration` and `include` (the overlay entry's Responses `include` values, possibly empty), present exactly
+ when `native` is `assumed`;
+ - `replay`: `assumed` or `unsupported`.
+
+ `native` is `assumed` when all of these hold, and `unsupported` otherwise:
+ - `runs_on` holds for the hop's (Source, model) and the tool (§3.1);
+ - no current negative `call` evidence exists for it (§3.2).
+
+ `replay` is `assumed` when `native` is, the protocol replays natively (`anthropic`, `openai_responses`), and no
+ current negative `replay` evidence exists.
+- **`image_generate`** gets `{models: [{source_id, model_id, description, params, size_forms}], default: {source_id,
+ model_id}}` (the endpoint kind and price stay gateway-side): every image model the user's Sources make available (§7.2), in the order the enum uses. The entry is
+ absent when the tool is off or no image model is available, so `models` is never empty and `default` never null.
+- **What goes away:** `mode` (Vibey decides), `executor` (the gateway resolves the chain per call), and every
+ dependence on positive evidence.
+- **The turn freezes the tool list.** A turn's first resolution fixes which tools the turn declares, one name per
+ tool whatever the mode, and the `image_generate` enum. Later hops of the turn change only `native` and `replay`.
+ A mid-turn tool-list change would break the cached prompt prefix and the model's view of its tools.
+
+### 3.5 Pinning, refusal and re-render
+
+v1's pinning stays: a request carrying Source-specific hosted content (a native declaration, a replayed native
+payload, or an in-flight continuation) is pinned with `x-avibe-pin-source`, is served only by that Source with no
+failover, and is refused unpinned (C-6 item 7). What changes is what happens after a refusal.
+
+- **The reason is machine-readable.** When the gateway answers a pinned request `pin_unavailable` because a narrow
+ hosted rule fired, the 409 body says which:
+
+ ```json
+ {"type": "error", "error": {"type": "model_hub_pin_unavailable", "code": "pin_unavailable",
+ "reason": {"kind": "hosted_unsupported", "tool": "web_search", "aspect": "call", "source_id": "src_…"}}}
+ ```
+
+ `reason` is present only when a narrow rule fired; the other `pin_unavailable` causes (the Source cannot be
+ admitted, a failover-class failure before output, #2626's identity hand-back) carry none, and `type` and `code`
+ are unchanged. The rule has already written the negative evidence (§3.2) when the answer leaves the gateway.
+ Vibey matches the 409 on `type` and `code` and tolerates extra fields (today's client matches the body exactly;
+ it relaxes in the same change).
+- **Vibey re-resolves; it does not render everything portable.**
+ - The adapter surfaces `pin_unavailable` as a terminal error with no partial and no output. The loop then
+ resolves a fresh hop, as it already does per model attempt (C-6 item 3), and renders that request normally for
+ it. Re-resolving applies only to a request whose response has produced no output, so it never discards streamed
+ content: a `pause_turn` continuation answered `pin_unavailable` still ends `interrupted` with its partial (§4.3). The fresh evidence turns exactly the refused tool into the proxy function or synthetic replay; other native
+ content stays native and pinned.
+ - This applies to every `pin_unavailable`, not only `hosted_unsupported`: a new identity drops the old payloads,
+ a Source in cooldown yields another hop with the in-place form. Fully portable rendering stays only as the last
+ resort.
+ - **Bounds.** At most one re-resolve per (turn, Source, tool, aspect) for `hosted_unsupported`, and at most two
+ re-resolves per turn across all reasons. When the fresh hop comes back on the same Source with the same facts,
+ Vibey renders portable at once instead of resending the same request.
+ - **In-flight content in the next request** (client tool results after server tools in the same assistant
+ message) keeps its hosted items verbatim only while the fresh hop still declares that tool natively. The
+ adapter's own `pause_turn` continuations are not re-rendered at all (§4.3). Otherwise the items take the
+ in-place text form (§4.4), because a provider refuses `server_tool_use` without its declaration.
+ - **A decrypt refusal** (§3.2, xAI) is mostly unpinned: xAI's encrypted reasoning (ThinkingBlock signatures,
+ `rs_…`/`tco_…` items) rides ordinary requests, and only hosted content pins. The gateway passes it through as the
+ provider's 400 on either path, so Vibey's adapter, its one classifier, recognizes that 400 before any output as
+ an opaque-payload refusal, and the loop re-resolves and renders with
+ **every** opaque payload of that Source identity dropped for the rest of the turn: signatures, encrypted reasoning
+ and native hosted payloads, since the refusal does not say which one failed. Once per (turn, identity); no
+ evidence is written (§3.2).
+- **The cost is one cold prompt prefix.** Dropping a native declaration changes the tools block, so the resend and
+ the next turns start a new cache prefix: once per (Source, tool), when the refusal is first learned, and again only
+ after the record is cleared (by the user or a stamp change) and the tool is tried natively once more. The upstream is not called twice
+ for nothing: a refusal before output costs no output tokens.
+- **The gateway never rewrites hosted content.** Vibey renders every request from its canonical records; the gateway
+ never swaps declarations or converts history. C-6 item 6's opaque thinking strip still applies to unpinned
+ requests only.
## 4. Vibey responsibilities
### 4.1 Request building
-| Protocol | Native declaration | Proxy declaration |
+| Protocol | Native declaration (`native: assumed`) | Function (otherwise, and always for `image_generate`) |
| --- | --- | --- |
-| `openai_responses` (OpenAI, xAI) | `{"type": "web_search"}`, `{"type": "x_search"}`, `{"type": "image_generation", "partial_images": 2, "output_format": "jpeg", "output_compression": 90}`, plus the overlay entry's `include` values. OpenAI's web search requires `include: ["web_search_call.action.sources"]`, merged with Vibey's existing `reasoning.encrypted_content`; without it, `action.sources` is not returned. xAI's `web_search_call` carried `action.sources` without it (spike). | `{"type": "function", "name": "web_search", "parameters": <canonical>}` |
-| `anthropic` | `{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}` | `{"name": "web_search", "input_schema": <canonical>}` |
-| `openai_chat`, `google` | none in Phase 1 | a function with the canonical schema. Vibey reaches a `google` hop over Chat Completions at the gateway (C-1 conversion tables), so the Chat form applies, and the engine translates it to Gemini `functionDeclarations`. |
+| `openai_responses` (OpenAI, xAI) | `{"type": "web_search"}`, `{"type": "x_search"}`, plus the overlay entry's `include` values. OpenAI's web search requires `include: ["web_search_call.action.sources"]`, merged with Vibey's existing `reasoning.encrypted_content`. | `{"type": "function", "name": <tool>, "parameters": <canonical>}` |
+| `anthropic` | `{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}` | `{"name": <tool>, "input_schema": <canonical>}` |
+| `openai_chat`, `google` | none | a function with the canonical schema. Vibey reaches a `google` hop over Chat Completions at the gateway (C-1 conversion tables), and the engine translates it to Gemini `functionDeclarations`. |
-- Vibey takes the mode from `HopResolution.hosted_tools`. It never decides nativity itself.
-- The probe and the proxy executor use these same declarations, `include` values included (§3.2, §3.4).
+- Vibey declares a search tool natively exactly when it is enabled and `native` is `assumed`; otherwise it declares
+ the same-named function. It never declares a hosted image tool.
+- Nothing forces a tool: `ModelRequest.tool_choice` and `forced_tool` existed only for probes and go (§11).
- Its four local tools are unchanged (C-7).
-### 4.2 Parsing: the C-1 change
+### 4.2 Parsing: the C-1 blocks
-The field tables below are the contract. The JSON Schema for them lands with the Phase 1 implementation PR, where a
-producer validates it (§12 lists every invariant it must encode).
+The v1 C-1 shapes stay, minus native images. The field tables are the contract; `message.schema.json` encodes them.
**Mapping rule.** Every item the provider emits for a declared hosted tool becomes exactly one `HostedToolBlock`,
in stream order, with a provider-neutral `action`. An action this design does not know becomes `other` and is kept,
@@ -305,548 +358,512 @@ never dropped.
| `web_search_call`, `action.type: open_page` | `web_search` | `{type: "open_page", url}` |
| `web_search_call`, `action.type: find_in_page` | `web_search` | `{type: "find_in_page", url, pattern}` |
| Anthropic `server_tool_use` (`name: web_search`) plus its `web_search_tool_result` | `web_search` | `{type: "search", queries: [input.query]}` |
-| xAI `custom_tool_call` `x_keyword_search` / `x_semantic_search` | `x_search` | `{type: "x_search", variant: "keyword" \| "semantic", query, limit?, mode?}`; `limit` and `mode` are kept when the call carries them |
+| xAI `custom_tool_call` `x_keyword_search` / `x_semantic_search` | `x_search` | `{type: "x_search", variant: "keyword" \| "semantic", query, limit?, mode?}` |
| xAI `custom_tool_call` `x_user_search` | `x_search` | `{type: "x_user_search", query}` |
| xAI `custom_tool_call` `x_thread_fetch` | `x_search` | `{type: "x_thread_fetch", ref}` |
-| OpenAI `image_generation_call` | `image_generation` | `{type: "generate", prompt: revised_prompt, size?}`; the image is saved to a file (§7.3) |
| any other item under a declared hosted tool | that tool | `{type: "other", name}`, with the provider's item name |
-**`HostedToolBlock`** (assistant content):
-
-| Field | Rule |
-| --- | --- |
-| `type` | `"hosted_tool"` |
-| `id` | canonical id |
-| `tool` | catalog name: `web_search`, `x_search` or `image_generation` |
-| `action` | one of the mapping rule's actions, with its fields required |
-| `record` | the `HostedRecord`, per-call facts only |
-| `native` | required: `{source_id, payload[]}`. `payload` holds the provider's own items, verbatim and in order, and is never empty. The payload's origin is the message's `origin`, not stored twice. No replay authorization is stored; replay is decided at every request from current evidence (§5). |
-
-A native hosted call always has its native payload. A proxied call is a `ToolCallBlock` plus
-`ToolResultMessage.hosted`, never a `HostedToolBlock`.
-
-**`HostedRecord`** (per call):
-
-| Field | Rule |
-| --- | --- |
-| `status` | `completed` / `failed` / `incomplete` / `pending` |
-| `error` | present exactly when `status` is `failed` or `incomplete`; bounded and redacted |
-| `sources[]` | this call's own results: `url` required; `title`, `snippet`, `page_age` optional. Empty when the provider returns none per call (xAI X search), except in a proxied call's record (§3.4). |
-| `images[]` | `image_generation` only: `{path, mime, width?, height?}` for each saved file. Never base64. |
-
-**`AssistantMessage.hosted_summary`** (per response, present when the message has hosted blocks). This is where
-response-scoped facts live, so nothing is copied into calls or split across them:
-
-| Field | Rule |
-| --- | --- |
-| `cost` | `{basis, usd}`: `basis` is `reported` (the provider's figure for the whole response, e.g. xAI `cost_in_usd_ticks`) or `list` (computed by the pricing module), and both carry `usd`; or `basis: included`, with no `usd` |
-| `counts` | provider-reported counters, by name (`web_search_calls`, `x_search_calls`, `x_posts_fetched`, `x_users_fetched`, Anthropic `web_search_requests`) |
-| `cited_sources[]` | sources the response cites when the provider gives none per call: the xAI X-search `url_citation`s to `x.com` / `twitter.com` |
-
-**`TextBlock.citations`** (optional): `[{url, title?, cited_text?, start?, end?}]`, with `start` and `end` together
-as a half-open code-point range into `text`.
-- Citations belong to the text that cites them. Every provider attaches them there: OpenAI and xAI `url_citation`
- with offsets, and Anthropic `citations[]` on text blocks.
-- They are presentation only and are never replayed.
-- **One materialization boundary.** At delivery, `core/citations.py` gains one builder from (text, citations) to
- the existing delivered shape: Markdown links written into the text, plus the sidecar the Web renders as
- `CitationBadge` (numbered sources, UTF-16 ranges, `body_sha256`). Adapters only parse; IM gets the Markdown links.
-
-**`ToolResultMessage.hosted`** (optional): `{record, execution?}`.
-- `execution` is a `ProxyExecution`: `mode: "proxy"`, `executor_origin`, `executor_source_id`,
- `executor_billing`, and `cost` when the pricing module can value the call. It is present exactly when an executor ran. A call that never
- reached one (none verified, or the bound Source removed) has none, and its `record.status` is `failed`.
-- `is_error` is `true` exactly when `record.status` is `failed` or `incomplete`.
-- So a proxied call renders like a native one, and the card names the exact Source even when two Sources share an
- origin.
-
-**Per adapter notes.**
-- **`openai_responses`.**
- - xAI's X-search `reasoning` items with id `tco_…`, which hold the tool output encrypted, stay ThinkingBlocks as
- today.
- - The `custom_tool_call` becomes the HostedToolBlock, and Vibey must not treat it as a local tool call. Today's
- adapter already ignores `custom_tool_call_input.*`.
-- **`anthropic`.** `encrypted_content` is kept only in `native.payload`. Text-block `citations` become `TextBlock`
- citations.
-- **`openai_chat`.** No native hosted results in Phase 1.
-- **Assembled-output budget.** Hosted payloads count against the existing 32 MiB `StreamAssembler` budget. Search
- events measured at most 96 KB.
+- **`HostedToolBlock`** (assistant content): `type` `"hosted_tool"`, `id`, `tool` (`web_search` or `x_search`),
+ `action`, `record`, and `native: {source_id, payload[]}` with the provider's own items verbatim and in order,
+ never empty. No replay authorization is stored; replay is decided at every request (§5).
+- **`HostedRecord`** (per call): `status` (`completed` / `failed` / `incomplete` / `pending`); `error` exactly when
+ `failed` or `incomplete`, bounded and redacted, with a stable `error_code` when Avibe wrote it (#2589);
+ `sources[]` (`url` required; `title`, `snippet`, `page_age` optional); `images[]` only on an `image_generate`
+ result (§7.3).
+- **`AssistantMessage.hosted_summary`** (per response, present exactly when the message has hosted blocks):
+ `cost` (`{basis, usd}` with `basis` `reported` or `list`, or `included` with no `usd`; absent when unknown),
+ `counts` (provider counters by name), `cited_sources[]` (the xAI X-search `url_citation`s).
+- **`TextBlock.citations`** (optional): `[{url, title?, cited_text?, start?, end?}]`, presentation only, never
+ replayed, materialized at delivery by `core/citations.py`.
+- **`ToolResultMessage.hosted`** (optional): `{record, execution?, action?}` for a proxied search call and for every
+ `image_generate` call.
+ - `execution` (`executor_origin`, `executor_source_id`, `executor_billing`, `cost?`) is present exactly when an
+ executor or image endpoint ran. Its `mode` is `proxy` for a search executor and `direct` for an image endpoint.
+ `executor_source_id`, `executor_billing` and `cost` are the attempt whose response the record came from;
+ `failed_attempts[]` lists the earlier billable attempts with their own billing and cost (§6).
+ - `action` is what the executor reports it did, beside the record, as today: for `image_generate`, the `generate`
+ action with the `model` used, the prompt it rendered, and the resolved size.
+ - `is_error` is true exactly when the record is `failed` or `incomplete`.
+- A native hosted call always has its native payload. A proxied search or an image call is a `ToolCallBlock` plus
+ `ToolResultMessage.hosted`, never a `HostedToolBlock`.
+- **Native image items are not hosted items.** Vibey never declares `image_generation` (and §7.1 keeps any caller
+ from receiving it), so an `image_generation_call` is ignored like any undeclared item, and a line over 8 MiB fails
+ the stream like any oversized line. The #2589 codes `image_not_streamed` and `provider_no_image` lose their
+ producers and stay in `HOSTED_ERROR_CODES` for records already written.
+- **rc-era transcripts are not migrated.** An rc session may hold an assistant row with a native `image_generation`
+ `HostedToolBlock`. No reader branch keeps that removed shape alive (owner directive; AGENTS.md forbids reintroducing
+ a removed optional-feature artifact through a compatibility shim), so such a session no longer loads its context
+ (§15).
+- **Per adapter notes.** xAI's X-search `reasoning` items (`tco_…`) stay ThinkingBlocks. The `custom_tool_call`
+ becomes the HostedToolBlock, never a local tool call. Anthropic's `encrypted_content` is kept only in
+ `native.payload`. Hosted payloads count against the 32 MiB `StreamAssembler` budget; search events measured at
+ most 96 KB, so every stream uses the 8 MiB line cap.
### 4.3 `pause_turn`
-- **Observed:** a 12-step dependent search chain paused after 10 server-side searches. The response ended with a
- `server_tool_use` that had no result.
-- **Continuing works:** resending the assistant content as is, with no new user message, was accepted. The server
- ran the pending search, and the answer completed.
-- **Today** `anthropic.py` maps `pause_turn` to `stop`, so that turn would end without its answer.
-- **Rule.** The Anthropic adapter continues internally: it re-issues the request with the paused content appended
- and keeps streaming as one logical response, at most 5 continuations.
- - Each continuation is pinned to the Source the paused response came from (§3.5). On `pin_unavailable`, the
- continuation is re-rendered in portable form, with the paused server blocks converted in place (§4.4), and goes
- out unpinned.
- - **As implemented (orchestrator decision, 2026-10-14):** a continuation goes only to the Source that served the
- paused response, pinned there, and is never re-rendered in portable form. A continuation that Source answers
- `pin_unavailable`, or a pause of a send that carried no pin, ends the response with one terminal
- `ProviderError(kind="interrupted")` whose partial keeps all assembled content, as at the bound. The merged
- message is then always one origin's, so no paused part needs a stored form other than the one it streamed in.
- The merged message is verified only when every response in it was verified and reported the same origin;
- otherwise it is sanitized as any unverified response. The case given up is rare: the pinned Source becoming
- unavailable seconds into a paused turn. The user keeps the partial answer and can retry. A turn's first request
- still gets its one portable resend on `pin_unavailable` (§3.5).
- - **After the 5th continuation**, if the response is still `pause_turn`, the adapter ends with one terminal
- `ProviderError(kind="interrupted")`. Its partial keeps all assembled content and the summed usage, and its
- `error_message` is "the provider paused the turn more than 5 times". C-2's existing rule then applies: terminal
- after text or a tool call, retried once after thinking alone.
- - C-2 still holds: exactly one `done` or `error`.
- - The paused partial and the continuation merge into one `AssistantMessage`.
- - Its `usage` is the **sum** of every continuation response's counters: input, output, and cache read and write.
- Today's parser resets usage at each `message_start`. The gateway already meters each continuation as its own
- call, so the usage ledger and provenance need no change.
- - **As implemented (orchestrator decision, 2026-10-14):** the merged message carries the **final** continuation's
- usage, not the sum. The context estimate anchors on a response's usage as the size of the request that produced
- it, and the final request's input already holds every paused part, so a sum would roughly double the next
- estimate. Billing and the ledger come from the gateway's per-call metering, and `hosted_summary` still sums
- counts and cost across continuations. Vibey-side token sums that read message usage, such as side-turn audit
- totals, undercount the earlier continuations.
- - **Pending calls carry over by id.** The adapter keeps its hosted blocks keyed by tool-call id across
- continuations. A result arriving in a continuation for a `pending` block finalizes that block, its `record` and
- its `native.payload`, so each call stays exactly one block.
- - **One `hosted_summary` for the merged message.** `counts` and `cost.usd` are summed over the continuation
- responses. `cost.basis` is `reported` only when every response reported a figure, and stays `included` on a
- subscription Source; otherwise the pricing module values the whole message at list price. `cited_sources` are
- deduplicated by URL in first-seen order.
+Unchanged from v1 as implemented (orchestrator decision, 2026-10-14):
+- The Anthropic adapter continues a paused response internally, at most 5 continuations, each pinned to the Source
+ that served the paused response. It never re-renders a continuation in portable form.
+- A continuation that Source answers `pin_unavailable`, a pause of a send that carried no pin, or a 6th pause ends
+ the response with one terminal `ProviderError(kind="interrupted")` whose partial keeps all assembled content.
+- The merged message carries the final continuation's usage; `hosted_summary` sums counts and cost and deduplicates
+ `cited_sources` by URL. Pending calls carry over by tool-call id, so each call stays one block.
+- The merged message is verified only when every response in it was verified and reported the same origin.
### 4.4 In-flight turn replay
-Within one turn, i.e. `pause_turn` or a client `tool_result` after server tools in the same assistant message, the
-next request is pinned to the Source the previous response came from (§3.5), and the assistant content goes back
-**verbatim**. This is the provider's own continuation contract, so it needs no `replay` evidence. Observed accepted:
-- a pending `server_tool_use` (the server then ran it);
-- ten `web_search_tool_result` blocks during a `pause_turn` continuation.
+Within one turn, a client `tool_result` after server tools in the same assistant message makes the next request
+pinned to the Source the previous response came from, and the assistant content goes back verbatim. (The adapter's
+own `pause_turn` continuations follow §4.3 and never take the fallback below.) This is the provider's own continuation contract, so it needs no `replay` evidence, but it does need the
+tool still declared natively on that hop (§3.5).
-**Fallback form.** It applies when the pinned Source rejects in-flight verbatim replay (a narrow 400), or answers
-`pin_unavailable`. Each server block pair is replaced **in place** by one text block: `[web_search: <query>]` plus
-numbered titles and URLs.
-- On the same origin, the signed thinking blocks stay untouched. This was accepted, with no signature error.
-- On a different origin, the C-1 cross-origin rules then apply to the rest of the message as usual.
-- Dropping the pair is never used: the model then misread its own turn ("I called read_file before the search")
- and redid the work.
-
-### 4.5 SSE caps
-
-Phase 1 needs no change: the largest search event was 96 KB, against an 8 MiB line and 32 MiB event cap. For
-images see §7.5.
+**Fallback form.** It applies when the pinned Source refuses in-flight verbatim replay, when the fresh hop no
+longer declares the tool natively, or on `pin_unavailable`. Each server block pair is replaced **in place** by one
+text block: `[web_search: <query>]` plus numbered titles and URLs.
+- On the same origin, signed thinking blocks stay untouched (accepted, with no signature error).
+- On a different origin, the C-1 cross-origin rules apply to the rest of the message.
+- Dropping the pair is never used: the model then misread its own turn and redid the work.
## 5. Replay and conversion
-These rules become C-1 rows in `cross-provider.md` and per-protocol rows in `conversion-tables.md`.
+These rules are C-1 rows in `cross-provider.md` and per-protocol rows in `conversion-tables.md`.
-| History item | All three hold: the target hop is `native.source_id`; the target's origin (provider, api, model) equals the message's `origin`; and `HopResolution.hosted_tools[tool].replay` is true now | Any other target |
+| History item | All three hold: the target hop is `native.source_id` under the identity that minted the payload (#2626); the target's origin equals the message's `origin`; and the hop's `replay` is `assumed` now | Any other target |
| --- | --- | --- |
-| `HostedToolBlock` | `native.payload` verbatim, in place | a synthetic same-named call plus result (Anthropic `tool_use` / `tool_result`, Responses `function_call` / `function_call_output`, Chat `tool_calls` / `tool` message), with the assistant message split around it. One record-to-text function (§3.4) renders the result, under the rules below. |
+| `HostedToolBlock` | `native.payload` verbatim, in place | a synthetic same-named call plus result, with the assistant message split around it. One record-to-text function renders the result. |
| `TextBlock.citations` | not sent | not sent |
-| Proxy call (`ToolCallBlock` + `ToolResultMessage.hosted`) | ordinary tool call and result | same |
-
-- **Google targets.** Vibey speaks Chat Completions to a `google` hop (C-1 conversion tables), so the Chat pair
- applies. The engine translates it to a Gemini `functionCall` part in the model turn and a `functionResponse` part
- in the next user turn, in the same order. A failed record becomes `response: {error: <text>}`.
-- **Synthetic rendering rules**, by action:
- - A `search` action becomes one call with arguments `{query: queries[0]}`. Its result lists any further queries,
- then the record's numbered sources (title, URL, snippet).
- - An `x_search` or `x_user_search` action becomes one `x_search` call with `{query}`, plus `limit` and `mode` when
- the action has them.
- - An `image_generation` action becomes one `image_generation` call with `{prompt}`, plus `size` when the action
- has it. Its result is the **text path record** (§7.3). Image bytes are never resent: no base64 and no image
- block, even to the same Source.
- - A non-search action (`open_page`, `find_in_page`, `x_thread_fetch`, `other`) is its own call with
- `{query: "<action type> <target>"}`. A completed one's result says what it did, e.g. "Opened <url>" or "Fetched
- thread <ref>".
- - **Deviation (orchestrator decision, PR #2561 review).** The design first folded such an action into the result
- of its tool's preceding call. Each rendering defect found in review came from that folding, where a line could
- land on a result that does not show it. So every hosted block is exactly one call, with its own status.
- - The response's `hosted_summary.cited_sources` are listed once, as "posts cited in the answer". They go on the
- first call that was not cut off, whether it is replayed as a synthetic call or in place.
- - A `failed` or `incomplete` record renders as an error result: Anthropic `is_error: true`, or text starting
- `[<tool> failed: <error>]` where the protocol has no error flag.
- - A `pending` record (a call cut off with the turn) renders as the C-1 interrupted-call result.
-- **Why synthetic beats plain text.**
- - Anthropic and Responses targets accepted the synthetic form, with the proxy or the native tool declared.
- - With snippets in the result, the target answered from it without searching again.
- - With plain-text rendering, Claude searched again.
-- **What is lost across providers: page text.**
- - Anthropic returns page content only as `encrypted_content`, which no other origin can read. OpenAI and xAI never
- return it.
- - The target sees queries, titles, URLs and snippets, and an honest model treats claims beyond them as unverified,
- as observed.
- - Provider-internal search state (opened pages, follow-up actions) is lost too.
-- **Vibey renders for the primary hop.** A request with native content is pinned, and its failover comes back to
- Vibey as `pin_unavailable` for a portable re-render (§3.5). So a different Source or origin never receives
- `native.payload`, and only Vibey ever converts it.
-- **C-6 change: the served-hop report gains `source`**, the serving Source id. Two Sources can share an origin, e.g.
- a subscription and a relay serving the same model. Native mode depends on this field three times: to tag
- `native.source_id` (§4.2), to authorize replay (above), and to pin in-flight continuations (§3.5).
- - It ships as a coordinated Model Hub contract bump, v12.
- - The orchestrator decided on 2026-10-13 to share the bump that #2483's provenance spec was deferred to.
- - That provenance fix then landed in #2544 within v11, without a bump. So this change now owns v12, and any other
- contract change pending at that time joins it.
- - The gateway and the served-hop parser change in that same release.
- - **Phase 1's native mode therefore lands with or after v12.** Proxy mode does not depend on it.
- - **The v12 bump edited these exact-shape contracts together** (Phase 1 foundation PR):
- - `model-hub-contracts/served-hop.schema.json` (new): the header is exactly `provider`, `api`, `model`,
- `source`. `hop-origin.schema.json` stays the persisted provenance origin (`provider`, `api`, `model`), because
- provenance attempts already carry `source_id` beside it and records written at v5–11 must keep validating;
- - `model-hub-contracts/vibey-consumer.md`, Response origin;
- - `agent-core-contracts/provider.md`, the served-hop sentence;
- - `agent-core-contracts/conversion-tables.md`, the Origin row;
- - `agent-core-contracts/model-hub-consumer.md`, item 4.
-
- A message's C-1 `origin` stays exactly `provider`, `api`, `model`; the served `source` tags `native.source_id`.
-
-## 6. User interface
-
-### 6.1 Models: the Tools tab
-
-- **One row per tool** (Phase 1: Web search, X search, Image generation), reusing the Sources tab's row and chip
- vocabulary (`chips.tsx`, `SourceRow`, `TimeHint`):
- - **toggle**, off by default;
- - **runs natively on:** chips per verified (Source, model), e.g. "xAI API key · grok-4.6 · verified 10-13";
- - **proxy executor:** a picker of verified candidates, each with billing mode and cost hint;
- - **cost per call:** "≈ $0.01 at API price" for metered, "included in subscription" for monthly, or "reported by
- xAI" when the last call returned a cost.
-- **Verify on…** lists the Sources whose overlay row offers the tool but that have no evidence. Each entry has an
- explicit **Verify** button showing the probe's estimated cost. Nothing probes on its own.
-- **Turning a tool on with no verified Source** opens that list. It never auto-probes.
-- **After an engine upgrade**, native evidence from the previous engine counts as unknown, so those tools run
- through the proxy. The tab says why in one header line, "Engine upgraded · N need re-verification" (zh:
- "引擎已升级 · N 项需重新检测"), with the existing check action listing those entries. Nothing re-probes in the
- background.
-
-### 6.2 Source detail chips
-
-Each model row on a Source's detail panel shows capability chips (capability model §5):
-- "Web search · native · verified 10-13";
-- "X search · via proxy";
-- "X search · not supported on this Source";
-- "ultra · not supported on this Source".
-
-Each has a **Re-verify** action with its cost. Unknown shows nothing.
-
-### 6.3 Defaults and onboarding
-
-- **Every tool is off by default.**
- - A call costs money on metered Sources.
- - It sends the user's queries to a third-party search.
- - Turning it on needs a cost-bearing probe.
- - No Source the owner has today makes it free. The ChatGPT subscription could, but it is untested.
-- **No onboarding step mentions tools.** The Tools tab is the only entry point.
-
-### 6.4 Use time in Vibey
-
-- **Tool card** (the existing `AgentActivityGroup` row; its `web` kind already shows a globe and a query chip):
- - the query;
- - the mode ("native · xAI API key" or "via proxy · Anthropic API key, claude-haiku-4-5");
- - the cost when metered;
- - an expandable source list (title, domain, age);
- - a failed status with its reason.
-- **Citations** render through the existing citation contract, using the one builder in §4.2: Markdown links plus
- the sidecar, which the Web renders as `CitationBadge`.
-- **IM** gets a compact single line, `🔎 Web search "query" · native (xAI) · 6 sources · $0.01`, and the answer
- carries plain Markdown links.
-- **Image generation card:** the prompt, the mode and the cost, with the image rendered inline from its file. IM
- attaches the file, with the same one-line form. The model sees only the path record (§7.3).
-
-## 7. Image generation (Phase 1)
+| Proxied search or image call (`ToolCallBlock` + `ToolResultMessage.hosted`) | ordinary tool call and result | same |
+
+- **Google targets** take the Chat pair; the engine translates it to Gemini `functionCall` / `functionResponse`
+ parts. A failed record becomes `response: {error: <text>}`.
+- **Synthetic rendering rules**, by action, unchanged from v1: a `search` becomes one call with `{query:
+ queries[0]}` whose result lists further queries and the numbered sources; an `x_search` or `x_user_search` becomes
+ one `x_search` call; every other action is its own call with `{query: "<action type> <target>"}`; the response's
+ `cited_sources` are listed once; a `failed` or `incomplete` record renders as an error result; a `pending` record
+ renders as the C-1 interrupted-call result.
+- **Replay is assumed, so a silent drop is possible.** A Source that accepts a replayed payload but silently drops
+ it leaves the model without the earlier results' page content (the answer text and citations stay in history).
+ Nothing in the response reveals it, so passive learning cannot see it. Known by design (§15); #2620 was this class
+ (the engine stripped xAI ciphertext for months without an error).
+- **What is lost across providers: page text.** Anthropic returns page content only as `encrypted_content`, which
+ no other origin can read; OpenAI and xAI never return it. The target sees queries, titles, URLs and snippets.
+- **The served-hop report carries `source`** (Model Hub contract v12), which tags `native.source_id`, authorizes
+ replay, and pins in-flight continuations.
+
+## 6. The search executor
+
+- **Endpoint:** `POST {base_url}/hosted-tools/{tool}` on the gateway, with the turn's Bearer token and its
+ `request_headers`, and the body `{"arguments": <canonical arguments>}`. There is no executor in the body: the
+ gateway resolves the chain from the caller's live turn (`x-avibe-turn-id`). A call without a live turn, or from a
+ turn that no longer admits work, is 409 `turn_not_live`; a tool outside the turn's frozen tool set (§3.4) is 409
+ `tool_not_enabled`. Nothing runs. v1's `executor_not_bound` is retired with the binding.
+- **The frozen tool set lives on the turn.** The turn's first resolution writes its tool set, each search tool's
+ effective executor order, and the `image_generate` enum, once to the turn trace (`hosted_tools`, replacing the
+ write-once `hosted_executors`). The endpoint authorizes every call against it, and a settings or Source-order change
+ applies from the next turn, as every runtime config change does.
+- **The turn still owns the call.** The endpoint stays authorized by the live named turn (#2586's `x-avibe-turn-id`
+ and closed admission); only the per-turn executor binding goes. Stopping the turn cancels the call, and it is
+ still metered. A candidate whose identity changed since the chain was built is not used.
+- **The chain, built at call time.**
+ 1. Candidates are the Sources whose vendor offers the tool natively (§3.1), with `runs_on` holding for the
+ vendor's `executor_model` and no current negative `call` evidence for that pair. So a subscription that does
+ not list the vendor's lightweight model is excluded when the chain is built, not found by a 404.
+ 2. Order: the turn's frozen effective order, which is the user's `executor_order` when set, then the remaining
+ candidates in Vibey's Source order, as they stood at the turn's first resolution. A Source added mid-turn joins
+ from the next turn.
+ 3. The gateway admits each candidate on the final snapshot, under the mutation lock, at the moment it calls it
+ (`runs_on`, identity, no negative `call` evidence), so a config change during the chain moves on instead of
+ calling a removed or re-identified Source. This is the same per-request admission every model request of the
+ turn already gets (C-6 item 3, #2616's identity rule): the turn freezes the order, not the Sources' runtime, and a
+ removed Source cannot be served at all. It calls the first admitted candidate: one short native request on
+ that Source's `executor_model`, with the
+ overlay's declaration, the tool forced where the protocol allows it (`tool_choice: "required"` on Responses;
+ Anthropic is asked in the message alone), a fixed instruction to search and list numbered results with one or
+ two cited sentences each, a small output cap, and no reasoning effort.
+ 4. On a failure that normal routing fails over from, or a narrow-rule refusal (which also writes negative
+ evidence), it tries the next candidate. A model refusal (404 `model_not_found`, "model not supported") skips
+ that Source for this call without settling its health, as `_InvocationUnsupported` does, and, because it names
+ the executor model, writes negative `call` evidence for (Source, `executor_model`, tool), so the Source leaves
+ the chain until the refusal is cleared or its wire stamp changes, and shows and clears like any refusal. A failure mid-stream moves on too: nothing
+ reaches Vibey until the gateway returns the record, so "before output" here means before the result is
+ returned, and the partial call is still metered on its Source. A completed response that never ran the tool
+ (the model chose not to; Anthropic is asked in the message alone) ends the chain with a `failed` record: it is
+ a model choice, not a Source failure, and moving on would double the cost. Any other outcome ends the chain.
+ 5. With no candidate, or every candidate failed, the call returns a `failed` record naming what to add ("add an
+ xAI Source to use X search").
+ - **One deadline for the whole chain**, the tool's call timeout (180 s for search), not one per candidate.
+ - Each candidate tried is metered on its own Source. The result's `execution` names the Source whose response the
+ record came from (the last one tried when all failed), with that attempt's `executor_billing` and `cost`; earlier
+ billable attempts are listed in `execution.failed_attempts: [{source_id, billing, cost?}]`, each with its own
+ billing and cost basis, so a metered failure before a subscription success keeps both. A subscription attempt
+ carries `cost: {basis: "included"}`, so an absent `cost` always means unpriced.
+ - **The total is computed once**, in `core/hosted_activity`'s projected `cost`, which the Web card and the IM line
+ both render: `usd` is the sum of the known figures over the record's attempt and `failed_attempts[]`; every
+ attempt `included` gives `included`; the basis is `reported` only when every summed figure is reported, else
+ `list` (shown with ≈); an attempt without a `cost` makes the total a lower bound, shown as "at least $X" /
+ "至少 $X", never as complete. With `failed_attempts`, the card also names the attempt count ("3 attempts" /
+ "尝试 3 次").
+ - The executor request is a short model request because no vendor exposes search without a model: Anthropic,
+ OpenAI's public API, xAI and Google all run search inside a model call.
+- **The result is the canonical record** (v1's rules, unchanged): a `HostedRecord` with `sources[]` in the
+ executor's order, a snippet from the answer text each citation covers (Anthropic keeps `cited_text`), X search
+ listing the cited posts, and the `ProxyExecution` naming the executor Source, model and billing. Every outcome of
+ a well-formed call is a 200 in the `ToolResultMessage.hosted` encoding; success is an allow-list on the response's
+ own completion status. Vibey's tool runtime renders the model-facing text with the same function that renders a
+ synthetic replay (§5).
+- **Cost.** One lightweight-model call plus the tool fee (xAI about $0.01 per call; Anthropic $0.01 per search plus
+ tokens), valued by the one pricing owner and shown on the card.
+
+## 7. Image generation: `image_generate`
### 7.1 No caller gets an image tool it did not declare
-- **Before.** The engine injected `{"type": "image_generation", "output_format": "png"}` into every Codex-executor
- request (CPA `ensureImageGenerationTool`): OpenAI API keys, the ChatGPT subscription and xAI keys, for any caller,
- Claude Code and OpenCode included. GPT could call it when asked for a picture, and the image was billed and then
- dropped.
-- **Codex no longer reports hosted image calls.** From Codex CLI 0.144.0 (2026-07-09, openai/codex#31596, "Use the
- image generation extension by default"), Codex produces images only through its own `image_gen` extension tool,
- which `codex-rs/core/src/tools/spec_plan.rs` (`image_generation_available`) gates to OpenAI-auth providers. A hosted
- `image_generation_call` in a response stream is no longer mapped to a turn item: `stream_events_utils.rs` maps only
- messages, reasoning and web search calls. So Codex emits no `imageGeneration` item, and Avibe's Codex backend
- (`event_handler.py` `_persist_generated_image`) has nothing to persist.
- - Observed in the 3.2.1rc4 release E2E with Codex CLI 0.162.1: the gateway and engine delivered the image intact,
- and Codex reported only the user and agent messages.
- - Avibe does not pin Codex: it installs `npm install -g @openai/codex`, the latest release. Every Codex it has
- installed since July 2026 is at least 0.144.0.
-- **Decision (orchestrator, 2026-10-13, revised 2026-10-14):**
- 1. The engine runs with `disable-image-generation: passthrough`, a fixed key in `config.py`. CPA then forwards
- requests with exactly the tools the client declared, never injecting and never stripping.
- 2. Nothing adds the tool back, for Codex CLI either. An injected tool only billed images that Codex then
- dropped.
- 3. Vibey declares `image_generation` itself, only when the user's toggle is on (§7.2).
-- **Effect.** No caller routed to a Codex-executor Source receives a hidden image tool. A user still on a Codex CLI
- older than 0.144.0 loses images through Model Hub that it used to show. Codex's own `image_gen` remains available
- wherever Codex enables it.
-- **Regression tests.**
- - **Gateway:** every caller (Codex CLI with an API key and with a subscription, Claude, OpenCode and Vibey)
- reaches the engine with exactly its declared tools, declared image tool or not (MH-HOSTED-GATEWAY-001).
- - The existing Codex image persistence tests stay unchanged; they cover Codex's own `image_gen` output.
- - **E2E once per release** (`tests/e2e/test_model_hub_codex_image.py`): the real engine in passthrough, a stub
- upstream and the real Codex CLI. A Codex turn through the Hub reaches the upstream with no image tool, and a Vibey
- request to the same Source with none either. Persistence is not asserted, because current Codex never reports
- a hosted image.
-
-### 7.2 Native and proxy
-
-- **Native** on verified OpenAI-protocol Sources. The probe is an `image_generation` call probe with a small image.
-- **Proxy** for other models: the executor is a verified image-capable Source. The executor saves the image as a
- file and returns its path record. A proxied call's result is the same text path record as a native one (§7.3).
-
-### 7.3 Files and a text path record (owner decision, 2026-10-13 19:14)
-
-- **The model is not given the image by default.** Each image is saved as a local file in the session's media
- store, decoded as the event is parsed.
-- **The model gets a text path record:** the file path, the revised prompt, the size, and the mode and cost, e.g.
- `[image saved: /…/image-3f2a.png · 1536×1024 · native (OpenAI API key) · ≈ $0.04] prompt: "…"`.
- - If the model wants to look, it opens the file with its `read` tool, the same as any other file.
- - The file the record names must fit `read`'s inline image cap. `MAX_INLINE_IMAGE_BYTES` in
- `core/agent_core/tools/read.py` is about 3.4 MiB, and `read` does not resize. A high-quality PNG of 4–6 MB would
- come back as "Image omitted". Phase 1 bounds it in the declaration: OpenAI's asks for `output_format: "jpeg"`
- at `output_compression: 90`, so a 1.6 MP image is about 0.3–1 MB, and every IM platform shows JPEG. An image
- still over the cap gets a record saying it is too large to view inline.
- - Known limitation: no transparent backgrounds in Phase 1. A later per-call format choice (an
- `output_format`/`background` argument on the tool) restores them.
- - A file is saved before the row that names it commits, and a cancel, crash or kill in between leaves a file no
- row references (orchestrator decision, 2026-10-14). One owner covers every such window (#2588):
- - the committed row registers each image it names in `media_objects`, in its own transaction, as an input
- snapshot is registered;
- - once per process, off the loop, Vibey's first recovery pass sweeps the agent media root;
- - the sweep removes a content-addressed file that no row registers, and a leftover temporary file, once either is
- older than 24 hours, longer than any Turn holds an uncommitted save;
- - each file costs one indexed lookup, and links and foreign names are never touched;
- - a save that reuses an old file makes it new again, so the sweep never takes a file a save is about to register.
-
- Generated images that pre-release builds committed without registering them are not kept (owner directive: no
- compatibility for pre-release states).
- - Avibe-authored failure reasons in a record's `error` are English model-facing text. Each carries a stable
- `error_code` (C-1 `HostedRecord.error_code`, one of `HOSTED_ERROR_CODES`), by which the display boundary localizes
- it; a provider's own reason carries none and shows as it is (#2589).
-- **The user sees the image.** The Workbench renders it inline from the file, and IM attaches it. That is display,
- separate from model context.
-- **History and replay never contain base64.**
- - `HostedRecord.images` holds the path records.
- - On the native OpenAI path, the transcript's `image_generation_call` item has its `result` replaced by the path
- record in `native.payload`.
- - Because a replaced `result` is no longer a valid image result, an `image_generation` block is never replayed
- verbatim. Every target, the producing Source included, gets the synthetic call plus the text path record (§5).
- The `replay` aspect is never probed for this tool.
-
-### 7.4 Byte flow and the idle bound
-
-- **Partial images.** Vibey's declaration requests `partial_images: 2`, so `response.image_generation_call.partial_image`
- events carry bytes during generation.
- - The gateway counts a partial image as model output (`stream_wire.py`), so response headers are released at the
- first partial.
- - Phase 1 drops previews: Vibey counts each one against the response's image budget and keeps none, so no preview
- reaches a file, history or model context, and the user sees the final image. Showing previews while an image is
- drawn is a later display change: a temporary file the final image replaces.
-- **What was measured.** A failing generation went 35.4 s without a byte after `generating`; healthy generations took
- 64–130 s.
-- **Phase 1 acceptance gate.** Through the gateway, with partials, the largest byte gap of every successful test
- generation stays under #2538's 120 s bound on `openai/openai_responses`. If it does not, the gateway treats an
- open `image_generation_call` as expected silence before Phase 1 ships.
-
-### 7.5 SSE caps
-
-- **Sizes on the wire.** One final image is about 4.1–4.2 MB of base64 at the relay's forced `quality: low`, and
- arrives **twice**: in `response.output_item.done` and in the engine-rebuilt `response.completed`. Each partial is
- another full image. High quality is plausibly 5.5–8 MB per copy.
-- **Vibey's limits for a Responses stream that declares `image_generation`:**
- - the line cap is raised from 8 MiB to the 32 MiB event cap;
- - image base64 is decoded to file as it is parsed and is excluded from the 32 MiB cumulative assembled-output
- budget;
- - the adapter takes the image from `output_item.done` and discards the duplicate `result` in `response.completed`
- without decoding it.
-- Other streams keep the 8 MiB line cap.
-
-## 8. Cost and limits
-
-- **Per-call prices** live in the overlay with date and source (capability model §6.2):
- - OpenAI web search: $10 / 1k calls plus content tokens;
- - Anthropic: $10 / 1k searches plus result tokens, re-billed while they stay in context;
- - xAI: web search $5 / 1k calls, X search $5 / 1k posts and $10 / 1k profiles;
- - OpenAI image generation: OpenAI lists no per-image price; image generation is billed per image token at the
- image model's rate (2026-10-13 pricing page). The overlay's `image_generation` entry therefore has no list
- price, and the cost comes from the call's image-token usage at that rate (Phase 1 pricing PR).
-- **Relays** show list price, labelled as such, and may bill differently.
-- **Anthropic OAuth policy:** a Claude subscription Source is never probed and never runs a hosted tool, whether
- natively or as proxy executor. Credential eligibility is checked before the probe, the native mode and the executor
- choice (§3.4, §3.5).
-- **Relay findings on 2026-10-13:**
- - the OpenAI relay did not complete web search (overload, 5/5), so it is unverified;
- - the Anthropic relay rejects cross-turn verbatim replay, so replay there is unsupported;
- - xAI is fully verified for calls and replay.
-- **Open:** OpenAI web search on a non-relay route, after the ChatGPT subscription's cooldown (2026-10-18).
-
-## 9. Phasing
-
-1. **Phase 0, capability foundation:**
- - the evidence store and narrow negative rules;
- - overlay `client_presets` on backend rows and the provider-neutral `providers` section (wire efforts, hosted
- tools, prices), with its loader and schema;
- - Source chips for efforts;
- - context-tier valuation.
- This closes #2539.
-2. **Phase 1, web search, X search and image generation:**
- - catalog, probes, the Tools tab, and the proxy executor;
- - `HopResolution.hosted_tools`, request pinning and `pin_unavailable`, and the V2 `hosted_tools` config;
- - the C-1 blocks and adapter parsing;
- - replay and conversion, `pause_turn` continuation, the tool card, and the IM line;
- - image generation (§7): engine passthrough with no injected tool for any caller, files instead of base64,
- partial images, and the SSE caps.
-
-## 10. Acceptance properties
-
-1. A hop receives a native hosted declaration only when all of these hold: the toggle is on; the credential is
- eligible; the (Source, model) has positive `call` evidence; and the path is untranslated. Every other hop gets
- the same-named proxy function.
-2. The gateway never rewrites hosted content. A request with native content is pinned, and every failure to serve
- it pinned comes back to Vibey as `pin_unavailable`. Vibey then sends it again in portable form.
-3. No hop receives `native.payload` unless it is the recorded Source and its `replay` evidence is positive at
- request time. The transcript stores no replay authorization.
-4. Every hosted call, native or proxy, yields exactly one canonical record. The card, citations and IM line render
- the same for either mode. One function renders a record to model-facing text, for proxied results and for
- synthetic replay alike. A failed record never renders as a successful empty result.
-5. Any transcript with hosted calls replays to any supported target without a history-shape error.
-6. `pause_turn` never ends a turn while its Source can continue it. Continuations are bounded, pinned to the
- paused response's Source, and merged into one message that carries the final request's usage and summed hosted
- counters (§4.3 as implemented). Past the bound, or when that Source cannot continue it, the turn ends with one
- `interrupted` error that keeps the partial.
-7. A generated image never enters model context or history as bytes. The model gets the text path record, and the
- user sees the image.
-8. No caller, Codex CLI included, reaches the upstream with an image tool it did not declare (§7.1).
-9. No probe and no proxy call runs without a user action or a model tool call in a turn the user started. Every
- probe shows its cost first.
-10. A real error creates evidence only through a narrow rule for the named (Source, model, feature).
-11. A shown cost says whether it is reported, at API price, or included in a subscription.
-
-## 11. Test plan
-
-The tests are hermetic: a local stub server plays each provider's hosted-tool responses from the spike's redacted
-shapes. No live upstream and no real credentials.
+Unchanged from v1 §7.1: the engine runs with `disable-image-generation: passthrough`, nothing adds an image tool
+back for any caller (Codex CLI included), and the gateway regression (MH-HOSTED-GATEWAY-001) and the once-per-release
+E2E stay.
+
+### 7.2 The tool
+
+- **One function tool**, declared on every protocol when enabled:
+
+ ```json
+ {"name": "image_generate",
+ "parameters": {"type": "object", "required": ["model", "prompt"], "properties": {
+ "model": {"enum": ["gpt-image-2", "grok-imagine-image", "gemini-3.1-flash-image"],
+ "description": "gpt-image-2: … (default) · grok-imagine-image: … · gemini-3.1-flash-image: …"},
+ "prompt": {"type": "string"},
+ "size": {"type": "string", "description": "e.g. 1024x1024, 1536x1024; or an aspect ratio such as 16:9"},
+ "images": {"type": "array", "items": {"type": "string"}, "maxItems": 4, "description": "paths of reference images to edit"},
+ "n": {"type": "integer", "minimum": 1, "maximum": 4}}}}
+ ```
+
+ - **The enum is the image models actually available**: the overlay's `image_models` (§3.1) for each Source where
+ `runs_on` holds for that model and no current negative `image_generate` evidence exists for the pair (§3.2: a
+ relay without the vendor's image endpoint refuses once and is then left out), deduplicated by model id (the first Source in Vibey's order serves an id that
+ two Sources offer, unless `default_model` names the other). Each entry's one-line description goes into the
+ `model` description; every line stays short, because the tool block is in every request's prefix. The default is listed first and marked "(default)"; the rest follow sorted by id. So the
+ enum is a pure function of configuration and current negative evidence, and the turn freezes it (§3.4). A
+ change (a config event, an image refusal or a clear) costs one cold prompt prefix on the next turn, as §3.5 says
+ for search.
+ - **Common parameters only.** `prompt`, `size` (a size or an aspect ratio, mapped per endpoint), `images`
+ (reference images for an edit) and `n`. The overlay's `params` say which of `size`, `images` and `n` each model
+ takes, and `size_forms` which forms of `size` it accepts (`pixels`, `ratio`, or both); the gateway maps the given
+ form to the endpoint's parameter. A `size` in a form the model does not accept is an unsupported argument. A call that passes one the chosen model does not take returns a `failed` record naming the argument and
+ the models that take it, before anything runs: silently dropping `images` would turn an edit into an unrelated
+ generation. Vibey's tool runtime refuses it before the call, from the turn's frozen `params`, so a bad call costs
+ nothing; the gateway validates again as the execution boundary.
+ - **Avibe-written failures carry stable codes** (#2589, `HOSTED_ERROR_CODES`): `image_param_unsupported` for an
+ argument the model does not take, and `image_model_unavailable` when the named model is no longer available
+ mid-turn. The UI adds copy for each.
+ - **No tool without a model.** With no image model available, `image_generate` is not declared at all, and the
+ Tools card says what to add (§8).
+- **The default** is `model_hub.hosted_tools.image_generate.default_model` (§3.3), else the first available model in
+ catalog order.
+
+### 7.3 Files and a text path record
+
+Unchanged from v1 §7.3 (owner decision, 2026-10-13 19:14), with the producer now the direct call:
+- **The model is not given the image.** The gateway returns the bytes to Vibey's tool runtime over the local hop;
+ Vibey saves them through the session media sink, the only writer of session media, and builds the `HostedRecord`
+ with `images[]` path records. The bytes are never in a transcript.
+- **The model gets a text path record:** path, model, size, mode and cost, rendered from the record, the result's
+ `generate` action (which now names the `model`) and its `execution`, e.g.
+ `[image saved: /…/image-3f2a.jpeg · 1536×1024 · gpt-image-2 (OpenAI API key) · ≈ $0.04] prompt: "…"`. It opens the
+ file with `read` if it wants to look. A request asks the endpoint for JPEG where the model allows it, so a file
+ fits `read`'s inline image cap; a file still over it gets a record saying it is too large to view inline.
+- **Media registration and the sweep** (#2588) are unchanged: the committed row registers each image it names, and
+ Vibey's first recovery pass removes unregistered content-addressed files older than 24 hours.
+- **The user sees the image.** The Workbench renders it inline from the file, and IM attaches it.
+- **History and replay never contain base64.** An `image_generate` call is an ordinary tool call and result, so it
+ replays as one to every target.
+
+### 7.4 Direct execution
+
+- **Never through a chat model.** Vibey never declares a hosted image tool on a chat request; v1's native
+ `image_generation` declaration, its partial images and its 32 MiB line cap are removed (§11).
+- **Endpoint:** the same executor endpoint, `POST {base_url}/hosted-tools/image_generate`, with `{"arguments":
+ {model, prompt, size?, images?, n?}}`. Vibey reads each reference image itself, exactly as `read` resolves a path
+ (relative to the session's cwd, under the same file permissions) and with its checks (a supported image type,
+ within `read`'s inline limit), and sends the bytes base64 in `images`. A path the agent could not `read` is
+ refused before any call, with a `failed` record whose error names the path.
+- **Per model kind** (the overlay entry says which):
+ - **OpenAI gpt-image family** (an OpenAI API key, or the Codex subscription backend) and **xAI grok-imagine**:
+ the engine's `/v1/images/generations`, or `/v1/images/edits` when `images` is present.
+ - **Gemini image models** (Nano Banana): the chat route with the image response modality, on the Source's own
+ protocol.
+- **Every route is unverified today** (gateway lane, 2026-10-15). The pinned engine (v8.0.23-3) contains the images
+ code (the Codex executor's direct Image API path, `gpt-image-2` entries, `grok-imagine-image-quality`, and
+ "model %s is only supported on /v1/images/generations and /v1/images/edits"), and `passthrough` keeps the images
+ endpoints enabled. None of it is reachable from Avibe yet:
+ - the engine adapter and `EngineClient` post only to the protocol endpoints, so they gain an images invoke path;
+ - `stream_wire` has no images taxonomy (outcome and usage), so it gains one;
+ - a custom (OpenAI-compatible chat) Source's image model needs the engine's per-model `image: true` flag, which
+ `config.py` never writes.
+- **Route verification is the implementation's job, not the user's.** Each image path gets one hermetic engine E2E
+ (the real engine, a stub upstream), like §7.1's harness: Codex OAuth images, an OpenAI API key, xAI
+ grok-imagine, and a Gemini image model (e.g. Nano Banana 2, `gemini-3.1-flash-image`) through the chat route
+ with the image modality. A model whose route is not verified ships without an overlay entry, so it is never
+ offered and the UI never needs an "unverified" tag.
+- **Authorized by the turn's enum.** The gateway resolves the Source from the turn's frozen `image_generate` enum
+ (§3.4): a model outside it is 409 `tool_not_enabled`, and the chosen (Source, model) is admitted on the final
+ snapshot (`runs_on` and identity). So a caller cannot bill an image model or Source the turn was not offered.
+- **Bounds.** The endpoint's 1 MiB request bound becomes per tool: `image_generate` allows its reference images,
+ at most 4, each within `read`'s inline limit, plus 1 MiB; the size check stays before parsing and the JSON parse
+ stays off the loop. `n` is at most 4, and decoded bytes are capped per image and per call as the executor caps
+ them today; a buffered response with several base64 images is parsed and size-checked off the loop.
+- **No idle cut for a buffered call.** The engine client's 120 s socket-read bound applies only to streamed calls on
+ the measured Sources, so a buffered images call longer than 120 s is not cut; the tool's call deadline bounds it.
+ If an images path ever streams partial images, those partials must keep feeding the idle bound.
+- **A Codex-subscription image runs through a chat model inside the engine.** The engine's Codex executor uses
+ either the direct Image API or the hosted `image_generation` tool on a base model
+ (`multimedia.gpt-image-2-base-model`, default `gpt-5.4-mini`), so such a call is billed and limited as a model
+ call. The subscription E2E covers whichever path the engine takes.
+- **No silent fallback.** A failed call returns a `failed` record whose error names the alternatives ("gpt-image-2
+ failed: <reason>. Available: grok-imagine-image, gemini-3.1-flash-image"). The model may call again with another
+ model; the gateway never switches on its own.
+- **The result names the model used**, in `ProxyExecution` and in the path record.
+
+## 8. User interface
+
+### 8.1 Models → Tools
+
+- **Grouped by capability**, one card per tool, each with one switch, on by default:
+ - **搜索**: 网页搜索, X 搜索;
+ - **生成**: 图片生成.
+- **The subtitle says where content goes**, plainly, because tools are on by default:
+ - en: "Tools Vibey can use in a conversation. Searches send the query to the vendor that runs them; if one fails,
+ the query may be retried with another of your Sources. Image prompts go to the image model's vendor. On metered
+ Sources each call is billed."
+ - zh: "Vibey 在对话中可使用的工具。搜索会把查询发给执行它的厂商,失败时可能改由你的其他供应商重试;图片提示词会发给图片模型的厂商。按量计费的供应商每次调用都会计费。"
+- **One status line per tool, from the read's `status` (§3.3), and only after something happened:**
+ - "最近一次由 <Source> 执行 · 正常 · 10-15" from `latest_ok`. It shows a date, not a time: positive records are
+ written at most hourly (§3.2);
+ - refusals come from `refused[]` grouped by aspect and then by `source_id` (the read stays per record), each group
+ with its newest `at` and its refused models, since evidence is per (Source, model) and the same Source may run
+ the tool on another model. Call refusals and replay refusals each get their own line under the rules below; a
+ Source with a call refusal appears only in the call line, since its replay refusal is moot while the tool is not
+ declared natively there. The two-or-more threshold counts distinct Sources across both lines:
+ - **one Source refused:** the status line reads "<Source> 不支持 · <models>" (joined with `Intl.ListFormat`), with
+ ",已改用 <Source>" appended when that newest `at` is older than `latest_ok` and `latest_ok` is on another
+ Source, and has a "清除" action for that (Source, tool);
+ - **two or more Sources refused** (owner-approved mockup, 2026-10-15): the status line names the Sources
+ ("A、B 不支持"), and the per-Source "清除" actions and "全部清除" sit in the card's **Advanced** section;
+ - the replay line reads "<Source> 不支持回放历史结果" (or "A、B 不支持回放历史结果"), since those Sources still run
+ the tool, and clears the same way;
+ - every clear uses the `clear` endpoint (§3.3). A cleared Source is tried natively again from its next request; if
+ it still refuses, the line comes back after that call. Refusals do not expire on their own (§3.2);
+ - nothing before first use. No "unknown", "unverified" or "unchecked" wording anywhere.
+- **Search cards** show an optional **Advanced** section (which also holds the clear actions when two or more
+ Sources refused) with the executor order over `executor_candidates`: up/down
+ buttons (keyboard- and screen-reader-accessible, the route chain editor's pattern), each row with its Source's
+ per-call price ("at API price" for a relay), collapsed and fully automatic until touched, with "Reset to
+ automatic" (a `null` PUT). The price shows per row because it depends on who runs the search.
+- **The image card** lists the available image models with their one-line descriptions and a per-image price
+ (owner-approved mockup): the vendor's list price where it has one (Grok Imagine "$0.02"); an estimate from token
+ pricing, marked "≈", where the image's tokens are known: the pricing module values the overlay's
+ `tokens_per_image` at the model's output token rate (Nano Banana "≈$0.067"); "暂无单价" / "no unit price" where
+ neither is (gpt-image-2, which OpenAI prices per image token at a varying count). It has a default-model picker over `default_model` / `effective_default`; a saved default that is no longer available
+ shows as itself, "(unavailable)". Image-endpoint refusals (§3.2) show and clear like search refusals; the image card
+ gets an Advanced section only when its clears move there (two or more Sources refused), holding only those; any other
+ failed image call shows only on its tool card in chat, since passive evidence keeps no other image failures. With no image model available, the card names the vendors from
+ `image_offered_by` ("Add an OpenAI or Google API key").
+- **Removed:** check and check-all, the confirm and result dialogs, Re-verify, the probe estimate, the executor
+ picker, and "engine upgraded" headers (§11).
+
+### 8.2 Source detail chips
+
+Each model row on a Source's detail panel shows only passive state, with the detail popover (time, basis, reason).
+There is no "via proxy" chip: proxying is the tool's business, not the Source's.
+- "网页搜索 · 正常 · 10-15", "图片生成 · 正常": a positive chip, with no action;
+- "X 搜索 · 不支持", "图片生成 · 不支持", "网页搜索 · 不支持回放", "ultra · 不支持": a refusal chip, whose popover has
+ "清除" (owner-approved mockup, 2026-10-15). A hosted-tool refusal chip clears both aspects of that tool for that
+ model, through the Tools `clear` endpoint with its `source_id` and `model_id` (§3.3); an effort refusal through the Source evidence clear (capability model §5). After a clear the
+ Sources and the hosted-tools read are both read again.
+
+A model row shows one chip per feature: when a positive and a negative record coexist (§3.2), the refusal chip
+wins, because it is routing state, and its popover may still name the last success ("曾于 10-15 正常"). A call
+refusal also hides that tool's replay chip, which is moot while the tool is not declared natively.
+
+Unknown shows nothing. The chips reuse `EvidenceChip`'s locale-composed spoken name and popup semantics, without the
+recheck action. Every chip stays focusable and opens its detail from the keyboard, positive or refusal, because the
+detail (time, basis, HTTP status and code) is content, not only a place for an action.
+
+### 8.3 Use time in Vibey
+
+Unchanged: the tool card (query, mode "native · xAI API key" or "via Anthropic API key · claude-haiku-5-5", cost
+when metered, sources, failure reason); citations through the existing citation contract; the IM one-liner
+`🔎 Web search "query" · native (xAI) · 6 sources · $0.01`. The image card shows the prompt, the image, the model
+used and the cost; IM attaches the file.
+
+## 9. Defaults, cost and privacy
+
+- **Every tool is on by default** (owner decision, 2026-10-15). This reverses v1's default, whose premise was that a
+ call costs money, sends queries to a third party, and needed a cost-bearing check to turn on. v2 removes the check;
+ the other two remain true and are stated in the public docs:
+ - a search sends the model's query to the vendor that runs it: the hop's provider natively, or the executor
+ Source's vendor via proxy; when an executor fails, the same query may go to the user's next executor Source,
+ which can be another vendor or the same vendor through another key or relay (§6);
+ - an image prompt and any reference images go to the chosen image model's vendor;
+ - on metered Sources each call costs the tool fee plus tokens (§10.4); on subscriptions it is included.
+- **No onboarding step mentions tools**, and nothing calls a provider unless the model calls a tool in a turn the
+ user started.
+- **Per-call prices** live in the overlay with date and source (capability model §6.2): OpenAI web search $10 / 1k
+ calls plus content tokens; Anthropic $10 / 1k searches plus result tokens, re-billed while they stay in context;
+ xAI web search $5 / 1k calls, X search $5 / 1k posts and $10 / 1k profiles. Image models show a per-image price on
+ the Tools card: the vendor's list price (Grok Imagine $0.02), or an estimate from token pricing marked "≈" (Nano
+ Banana ≈$0.067), or "暂无单价" (gpt-image-2); a real call shows its reported or valued cost, never zero for
+ unknown.
+- **Relays** show list price, labelled "at API price", and may bill differently.
+
+## 10. Contract changes
+
+The contract edits land with the implementation PRs as one coordinated Model Hub version event after #2626's v14,
+under the freeze protocol (`model-hub-contracts/README.md`).
+
+### 10.1 C-1 (`agent-core-contracts/message.schema.json`, `cross-provider.md`, `conversion-tables.md`)
+
+- A `HostedToolBlock` has `tool` `web_search` | `x_search`, written and read; an rc-era `image_generation` block is not
+ accepted (§4.2, §15).
+- `ToolResultMessage.hosted` keeps `{record, execution?, action?}`. `record.images[]` and `action: generate` occur
+ only for `image_generate`; `generate` gains the `model` used, with `prompt` required for a `completed` record.
+- `ProxyExecution` becomes the result's `execution` with `mode: "proxy" | "direct"` (direct for an image endpoint)
+ and `failed_attempts[]` (`{source_id, billing, cost?}`) for the earlier billable attempts of a search chain. `core/hosted_activity` maps `direct` beside `proxy` for the
+ tool card and the IM line.
+- `HOSTED_ERROR_CODES` gains `image_param_unsupported` and `image_model_unavailable` (§7.2), with UI copy for each.
+- The conversion rows drop native image replay; an `image_generate` call is an ordinary tool call everywhere.
+
+### 10.2 C-6 (`agent-core-contracts/model-hub-consumer.md`, both `hop-resolution.schema.json` copies)
+
+- `HopResolution.hosted_tools` entries become `{native: "assumed" | "unsupported", declaration?, include?, replay:
+ "assumed" | "unsupported"}` for search tools (§3.4), and `image_generate: {models[{source_id, model_id,
+ description, params, size_forms}], default}`; `mode` and
+ `executor` are removed. `declaration` and `include` are present exactly when `native` is `assumed`.
+- Admission of a pinned request reads negative evidence only: a declared native tool needs `runs_on` and no current
+ negative `call` evidence; a replayed item needs no current negative `replay` evidence.
+- The `pin_unavailable` envelope gains `reason` (§3.5).
+- The executor body is `{"arguments"}` only; the gateway resolves the chain from the live turn (§6). The endpoint
+ keeps turn ownership; it authorizes each call against the turn's frozen tool set and, for `image_generate`, its
+ enum. Errors are 409 `turn_not_live` and `tool_not_enabled`; `executor_not_bound` is retired.
+
+### 10.3 Model Hub contracts
+
+- `capability-evidence.schema.json`: `basis` is `observed` only; `status` `verified` (display only) or
+ `unsupported`; `shape` is removed and `engine` becomes `wire`, the stamp of §3.2; `feature.name` is `web_search`
+ | `x_search` | `image_generate`, and `image_generate` has `call` only.
+- `hosted-tools-status.schema.json` is rewritten for §3.3's read: per tool `enabled` and `status {latest_ok,
+ refused[]}`; search tools `executor_order`, `effective_order`, `executor_candidates[]`; `image_generate`
+ `default_model`, `effective_default`, `models[]`, `image_offered_by[]`. `reverify`, `executor`, `bound` and
+ `candidates[]` (with `call`, `replay`, `probe_estimate`) go. The PUT body is per field (§3.3).
+- `hosted-tool-probe-result.schema.json` is deleted, with its `api-response.schema.json` branch and `api.md` row.
+- `refused_efforts[].changes_at` (`agent-chain.schema.json`, `source.schema.json`) loses its meaning, since nothing
+ expires by age: it is removed with its UI expiry hint (`capability.expiryProbe` and the observed-expiry copy); the
+ hosted-tools read already drops it (§3.3).
+- `api.md` gains `POST /api/models/hosted-tools/<tool>/clear` (`{source_id?}` → the read, §3.3) and
+ `POST /api/models/sources/<source_id>/evidence/clear` (`{model_id, feature}` with an effort feature → the Source,
+ for an effort refusal; capability model §5), each with its `api-response.schema.json` branch.
+- `provider-overlay.schema.json` gains `executor_model` per vendor and `image_models[]`.
+- V2 config: `model_hub.hosted_tools` as §3.3.
+
+### 10.4 Pricing
+
+- No `probe_estimate`. Cost is reported or valued per real call: `hosted_summary.cost` for native calls, and
+ `ProxyExecution.cost` for executor and image calls.
+- Image calls are valued from the overlay's image price where the vendor lists one, else from reported usage at the
+ image model's token rate; unknown stays unknown, never zero.
+
+## 11. Removal list
+
+| Area | Removed or changed |
+| --- | --- |
+| Model Hub | `core/handlers/model_hub/hosted_probe.py`; `ModelHubService.probe_hosted_tool`, `_record_probe_evidence`, `_probe_estimate`, `_probe_rejection`, `_probe_aspect`; the RPC and UI-server routes for `POST /api/models/hosted-tools/<tool>/probe`; `MODEL_HUB_RPC_TIMEOUT_SECONDS`' probe dependency (it moves back to `vibe/model_hub_client.py`); `HOSTED_PROBE_SHAPE` and every `shape` parameter; the evidence `probe` basis and probe staleness; `engine_stamp()`'s `hosted_wire` branch (#2623); the per-turn executor binding and `_executor`; `UserTestCall`'s probe-only callers |
+| Gateway | `stream_wire`'s `response.image_generation_call.partial_image` model-output envelope; the executor's native image path (`ResponsesStreamReader(partial_images=…)`, the 32 MiB image line cap, the image event and byte budget, `_image_result`, the `_IMAGE_*` constants, the 300 s image `call_timeout`), replaced by what the images endpoint needs; the OpenAI `image_generation` overlay declaration (#2580's JPEG q90 becomes the images-endpoint request parameters); `executor` in the proxy body; `executor_request`'s image branch (its `include`/`partial_images` read of the overlay image declaration); the `hosted_executor_bindings` / `turn_hosted_executors` plumbing, replaced by the turn's frozen `hosted_tools` (§6); the `hosted_tools_status` candidates and bound-executor projection. `_own_turn_call` stays. Kept: `disable-image-generation: passthrough`; `hosted_admission`'s "image calls are never replayed" rule until no transcript can carry a native image call; #2616's per-turn identity binding and #2586's turn id. |
+| Vibey | the native `image_generation` declaration, its parsing (`responses_hosted_tool`'s `image_generation_call` mapping, `image=`/`image_error=` in `responses_hosted_block`), `_ImageBudget`, `_saved_image`, `_PARTIAL_IMAGE_EVENT`, `IMAGE_STREAM_LINE_BYTES`, the large-event JSON offload, `drive_sse_stream`'s `max_line_size` and `iter_sse_events`' offload (every stream returns to 8 MiB); `ModelRequest.tool_choice` and `_common.forced_tool`; `registry.build_wire_request` (its tests move to each adapter's `wire_request`); the adapters' probe-only `media_sink` parameter and the `media_sink` argument of `registry_providers(media_loader=…, media_sink=…)`; `HostedTool`'s `executor` field and its `executor` body; the agent's `_with_hosted_images` / `_emit_orphan_images` path for native images (`agent.py`), kept for `image_generate` results. `HostedRecord.images`, `HostedImage`, `generate_action` and the `generate` action stay, on `ToolResultMessage.hosted` only. |
+| UI | `ProbeAnswerNote.tsx` (with `ReplayNote`); in `ToolsTab.tsx` `ProbeCell`, the executor picker and its notes, the `needsCheck`/`needsExecutor` states, the "unchecked" chip and the probe column; in `HostedCapabilityChips.tsx` the recheck action, the recheck-only keyboard path (every chip keeps its keyboard path into the detail), and the reverify, engineUpgraded and unsupportedAged states; `useEstimateLabel.ts`; the `probeHostedTool` wiring in `SettingsModelsPage.tsx`, whose Sources re-read after a probe moves to after a clear (the Source chips show the same refusals); in `useHostedTools` `probe`, `probing`, `lostProbeOutcome`, `recordedOutcome` and `PROBE_NOT_RECORDED` (the serialized writes, identity fencing and re-read after Source mutations stay); in `hostedTools.ts` `ProbeTarget`, `probeKey`, `probeUnanswered`, `verifiedCandidates`, `sameExecutor` and the `aged`/`engineUpgraded` branches of `evidenceChip`; `modelsApi.probeHostedTool`; the types `HostedToolProbeResult`, `HostedProbeAspect`, `HostedCostEstimate`, `probe_estimate`, `HostedToolCandidate`, `bound`, and `executor` in `HostedToolPut`. Rebuilt on the new read rather than only trimmed: `modelCapabilities` and the Tools-tab rows on `status`; `cost.imageTokens` ("no per-image price yet") by per-image prices; `capability.chip.viaProxy` and `explain.viaProxy` go with the "via proxy" chip. Check-all is removed by the UI lane's pending PR. |
+| i18n (`settings.models`) | `tools.probe.*`; `tools.state.needsCheck` and `needsExecutor`; `tools.executor.*`; `tools.chip.unchecked`, `reverify`, `engineUpgraded`, `unsupportedAged`; `tools.reverify.*`; `capability.recheck`, `recheckCost`; `capability.chip.*` and `capability.explain.*` for reverify, engineUpgraded, viaProxy, viaProxyAged and unsupportedAged; `capability.expiryProbe`; `tools.col.*` and `tools.chip.native`/`unsupported`/`executor` (the candidate table goes). Rewritten: `tools.subtitle` (§8.1), `tools.empty` and `tools.noNative` against the new read; `tools.footnote` keeps its relay and subscription sentences. |
+| Tests and scenarios | `tests/test_model_hub_hosted_probe.py`; the probe and executor-binding cases in `test_model_hub_hosted_tools_resolution.py`, `test_model_hub_hosted_executor.py`, `test_model_hub_hosted_pinning.py` and `test_model_hub_evidence_rules.py`; the native image cases in the Responses adapter tests; UI `ToolsTab.test` MH-HOSTED-UI-013 and 019, the executor cases of 001 and the probe parts of 003 and 018, `useHostedTools.test` 013 and parts of 007, `hostedTools.test` 013, `SourceDetailPanel.test` 013 and 017, `SettingsModelsPage.render` 016; catalog rows MH-HOSTED-007 (probe), UI-004 (the engine-upgraded and aged header), UI-013, UI-016 and UI-019 retire; UI-002 shrinks to the passive states; UI-018's "locked until verified" becomes "on by default, nothing locks"; UI-001's write contract becomes the per-field PUT |
+| Contracts | as §10 |
+
+## 12. Implementation split
+
+Each phase is one or more PRs under the normal gates. The contract version event (§10) rides the first PR that
+edits a frozen file, and later phases join it if it has not shipped. The C-1 additions the display reads (`execution.mode: "direct"`
+and the codes `image_param_unsupported` and `image_model_unavailable`) land in the producer PR (phase C), before
+phase D's display work; that PR adds the codes' en and zh copy in `vibe/i18n` and `ui/src/i18n`, because
+`test_every_known_hosted_error_code_has_copy_on_every_surface` requires copy for every known code.
+
+| PR | Lane | Work | Depends on |
+| --- | --- | --- | --- |
+| **A1** Evidence, priors, settings | foundation | the evidence model: status-keyed records with `mode`, negative-only routing, no time limit (efforts included), the in-memory `wire` stamp computed at `sync_sources`, memory updated when a refusal's write fails, no `probe` basis or `shape`, the `hosted_wire` branch gone; the positive rule's entry point, which B1's observer calls; the clear endpoints (hosted and effort) with their edge and persistence rules; overlay `executor_model` and `image_models` (schema and loader; image entries land with B2); the `hosted_tools` config v2 with the generic loader rule; the hop-fact functions (§3.4) and the image enum function; the `hosted-tools-status` v2 read and per-field PUT with the `latest_ok` projection; removal of the probe stack (§11 Model Hub); the Model Hub contracts of §10.3 and the coordinated version event | — |
+| **B1** Signal, refusal, executor chain | gateway | the observer's projection paths and the positive write at settlement (§3.2); `pin_unavailable.reason` and admission on negative evidence only; `HopResolution.hosted_tools` v2 from A1's facts, frozen in the turn trace with the executor order and the image enum; the executor chain (§6) with `{arguments}` bodies, `turn_not_live` / `tool_not_enabled`, failover, one deadline, `failed_attempts`, and the executor-model refusal; the C-6 text (§10.2); gateway removals (§11) | A1 |
+| **C1** Declarations and re-render | Vibey | declarations from facts and the turn freeze; the 409 matched on `type` and `code`; `pin_unavailable` surfaced to the loop and re-resolve with its bounds; the decrypt refusal; the in-flight rule; the C-1 changes of §10.1 (`execution.mode`, `failed_attempts`, `generate.model`, the two image error codes with en and zh copy); the localized context-load error for a row that no longer validates; Vibey removals (§11) | B1's HopResolution and executor body: developed on B1's branch and merged together with it |
+| **B2** Image endpoints | gateway | the engine images invoke path, `stream_wire`'s images taxonomy, the per-model `image` flag, the image narrow rule (upstream refusals only), request and response bounds, enum authorization; one hermetic engine E2E per image path; the overlay `image_models` entries for the paths that pass | A1, B1 |
+| **C2** `image_generate` | Vibey | the tool with the enum and `params` / `size_forms` validation before the call, reference images read as `read` reads them, the path record from record, action and execution | C1, B2 |
+| **D1** Tools tab and chips | UI | the grouped Tools tab, status lines per aspect with their clears, Advanced (executor order, clears), the per-field PUT, Source chips with clears and precedence, the picker's refused-effort note; removals (§11 UI, i18n); the Tools-tab and chip frames in `avibe-docs/design.pen` through Pencil (the Pencil MCP must be connected on that host) | A1's read and endpoints; B1 for live positive records |
+| **D2** Image card and direct calls | UI | the image card (models, prices, default, Advanced clears), `core/hosted_activity`'s cost total and the `direct` mode on the card and the IM line | C2, B2 |
+| **E** Public docs | foundation | what each tool does, default-on, where content goes, cost (§9) | D1, D2 |
+
+## 13. Acceptance properties
+
+1. Nothing calls a provider to learn about a tool. Every provider call comes from a model's tool call or a model
+ request in a turn the user started.
+2. Every tool is on unless the user turned it off; a released config without the section has every tool on.
+3. A hop declares a search tool natively exactly when it is enabled, `runs_on` holds, and no current negative
+ evidence exists; every other hop gets the same-named function.
+4. Positive evidence never changes routing. Negative evidence comes only from a narrow rule, names one (Source,
+ model, feature), and stops applying only when the user clears it or the wire stamp it was learned under changes
+ (the Source's config, the engine release or the Avibe release). It never expires by age.
+5. A refusal a narrow rule names reaches Vibey as `pin_unavailable` with its reason; Vibey re-resolves and resends
+ with that tool as a function, within the bounds of §3.5. The gateway never rewrites hosted content.
+6. No hop receives `native.payload` unless it is the recorded Source under the identity that minted it, on the same
+ origin, with `replay` assumed now.
+7. A proxied search tries executors in the user's order, then Vibey's Source order, each on its vendor's
+ lightweight model, and fails over on failover-class failures and narrow refusals only.
+8. `image_generate` runs on exactly the model the call names; a failure names the alternatives and never switches
+ model. The result names the model, and no image byte enters model context or history.
+9. Every hosted call, native or proxy, yields exactly one canonical record, rendered the same way on the card, in
+ citations and on IM.
+10. Any transcript with hosted calls replays to any supported target without a history-shape error.
+11. The UI shows only what real use learned; no state reads "unknown", "unverified" or "unchecked".
+12. A shown cost says whether it is reported, at API price, or included in a subscription.
+
+## 14. Test plan
+
+Hermetic: a local stub server plays each provider's responses from the spike's redacted shapes. No live upstream
+and no real credentials.
| Layer | Owner boundary | Cases |
| --- | --- | --- |
-| Adapter parsing | each adapter against stub SSE | the mapping rule, one case per row of §4.2's table, including `queries[]` versus the deprecated `query`, every xAI X-search variant, and an unknown item becoming `other`; `hosted_summary` with one and with several X searches (reported cost once, no per-call copies); Anthropic citations; pending `server_tool_use` at `pause_turn`; a hosted call that fails |
-| Cross-provider transform | `ai` request builders | each hosted block to each target, verified same Source versus other: native verbatim, synthetic call/result, split assistant message; citations never sent |
-| `pause_turn` | Anthropic adapter, stub returns `pause_turn`, then `end_turn` | one logical response; the bound; the merged message with the final request's usage and summed hosted counters; the pin header; `pin_unavailable` on a continuation ends `interrupted` with the partial (§4.3 as implemented) |
-| Gateway selection and pinning | real gateway + loopback fake engine | native only with evidence and an eligible credential; a pinned request is never failed over; an inadmissible pinned Source and a pre-output failure both answer `pin_unavailable`; Vibey's portable re-render is then served by failover; `x_search` to OpenAI never sent |
-| Evidence | classifier against recorded error bodies | `400 Unsupported tool type`, `invalid_value` effort and `Invalid encrypted_content` each create exactly one record; overload and 5xx create none |
-| Proxy executor | gateway endpoint, stub provider | executor choice; no effort sent; the record with excerpts; metering on the executor Source; error when no executor is verified; refusal of a Claude subscription |
-| Record rendering and citations | the record-to-text function; `core/citations.py` builder | completed, failed, incomplete and pending records; every action's synthetic rule; summary cited sources listed once; provider annotations through to the Web sidecar and the IM Markdown link (end to end) |
-| Config | `ModelHubConfig` loader | a released config without `hosted_tools` loads with all tools off; an unknown tool key degrades with a warning |
-| Declared tools only | gateway + loopback fake engine | Codex (API key and subscription), Claude, OpenCode and Vibey requests reach the engine with exactly their declared tools; the existing Codex image persistence tests unchanged |
-| Images | Responses adapter against stub SSE | partials then a final image twice: one file written, no base64 in history, the duplicate in `response.completed` not decoded, a 9 MiB image line accepted under the image cap, the text path record as model context |
-| Probes | gateway, stub provider | verified / unsupported / dropped / transient outcomes; a replay probe whose answer lacks the first search's URL is `unsupported`; probes only from the API action |
-| UI | Models Tools tab, Source chips, tool card | toggle off by default; Verify shows the cost; chips per evidence state; card modes; IM line |
-| E2E, once per release | real engine + stub upstream | a native web search and a proxied X search through the shipped engine on each protocol |
-
-## 12. Contract checklist for the Phase 1 schemas
-
-The JSON Schemas land with the Phase 1 implementation PR. There, a producer validates them, through the existing
-`_validate` and mandatory-field tests for `HopResolution`, and new ones for the C-1 blocks. Each invariant below is
-encoded either as a schema clause or as a producer test. The PR names which for each item.
-
-**C-1 `message.schema.json`:**
-1. `HostedToolBlock` requires `type`, `id`, `tool`, `action`, `record` and `native`.
- - `native` requires `source_id` and a non-empty `payload`.
- - It has no origin of its own and no replay flag.
-2. `action` is one of the mapping rule's types (§4.2), with that type's fields required:
- - `search` with `queries`, at least one;
- - `open_page` with `url`;
- - `find_in_page` with `url` and `pattern`;
- - `x_search` with `variant` and `query`, and optional `limit` and `mode`;
- - `x_user_search` with `query`;
- - `x_thread_fetch` with `ref`;
- - `generate` with `prompt`, and optional `size`;
- - `other` with `name`.
- - `generate` is valid only when `tool` is `image_generation`, and `images[]` is present exactly then.
- - No field anywhere holds image base64.
-3. `HostedRecord`: `status` is in its enum. `error` is present exactly for `failed` and `incomplete`. Each
- `sources[]` entry requires `url`.
-4. `AssistantMessage.hosted_summary`:
- - it is present exactly when the message has a `HostedToolBlock`;
- - `counts` and `cited_sources` are required (possibly empty); `cost` is optional, absent when no price is known,
- because unknown is never priced as zero;
- - `cost.usd` is present exactly when `basis` is not `included`.
-5. `TextBlock.citations`: `start` and `end` come together.
-6. `ToolResultMessage.hosted` requires `record`. `execution` is present exactly when an executor ran; without it,
- `record.status` is `failed`.
- - `execution` requires `mode: "proxy"`, `executor_origin`, `executor_source_id` and `executor_billing`; its
- `cost` is optional on the same rule as item 4.
- - `is_error` is `true` exactly when `record.status` is `failed` or `incomplete`.
-
-**C-6 `HopResolution.hosted_tools` (both copies):**
-7. Each entry requires `mode`, `replay` and `executor`.
- - `executor` is `{source_id, model_id}` or `null`, and is present for every entry whatever the mode.
- - `declaration` and `include` (the overlay entry's Responses `include` values, possibly empty) are present exactly
- for `native`.
- - `hosted_tools` itself is required, and empty when no tool is enabled.
-
-**Model Hub:**
-8. V2 `model_hub.hosted_tools`: keys are catalog tool names, and each entry requires `enabled` and `executor`.
- - `executor` is `null` or a pair of non-empty ids.
- - An unknown key degrades with a warning.
-9. Overlay `providers` entries and the evidence record follow the field tables in the capability model (§3.1, §4),
- including: `observed` ⇒ `unsupported` with `detail`.
-10. The `pin_unavailable` answer is exactly the 409 envelope in §3.5.
-11. Native replay requires all three: same Source, same origin, and current `replay` evidence. `image_generation`
- blocks are never replayed verbatim, and their synthetic call carries `size` when the action has it.
-12. A probe with no tool item is inconclusive and writes no evidence.
-13. The engine config renders `disable-image-generation: passthrough`, and no caller, Codex CLI included, reaches the
- engine with an image tool it did not declare (§7.1).
-
-**Added after review of the final design head (implementation-level, binding on the Phase 1 PR):**
-
-14. A probe resolution exists only for the user's probe action. It pins the probed (Source, model), carries the
- overlay's native declaration whatever the current evidence, and allows no failover (§3.2).
-15. The executor request depends on the tool: search tools search and list results; `image_generation` renders the
- supplied `prompt` and `size` (§3.4).
-16. Across `pause_turn` continuations, a result for a `pending` block finalizes that block by tool-call id. The
- merged message has one `hosted_summary`, with summed `counts` and `cost.usd` and URL-deduplicated
- `cited_sources` (§4.3).
-17. Image cost is valued from the call's image-token usage at the image model's per-token rate, because OpenAI
- lists no per-image price (capability model §4). If a vendor later lists per-image prices, those entries are
- keyed by the resolved `quality` and `size` (item 22).
-18. The image file a path record names fits `read`'s `MAX_INLINE_IMAGE_BYTES`, tested with a 6 MB generated image
- (§7.3).
-19. The executor binding is held for the turn. Only removal or disablement of the bound Source makes a call fail,
- with a tool error and no Source switch (§3.4).
-20. Hosted-tool `call` and `replay` evidence whose `engine` or `shape` differs from the current one resolves as
- unknown: proxy mode and synthetic replay. Age-only staleness keeps routing. Effort evidence is unchanged
- (capability model §3.3, §3.4).
-
-**Added after review of the merged design (implementation-level, binding on the Phase 1 PRs):**
-
-21. Continuations merge into one `AssistantMessage` only when the served-hop report shows the same origin. A
- `pin_unavailable` continuation served by another origin makes the merged message take the serving origin, and
- the paused part is kept in the portable form that was actually sent (§4.4 fallback, C-1 cross-origin rules), so
- no payload or signature from the first origin remains.
- **As implemented (orchestrator decision, 2026-10-14):** there is no portable continuation, so no cross-origin
- merge (§4.3). A continuation whose response reports another origin, or none, leaves the merged message
- unverified, so it keeps no payload or signature of any response.
-22. The `generate` action records the output's resolved `quality` and `size`; pricing uses those output values, not
- the declaration's.
-23. The replay probe asks for a result URL the call returned that its visible answer does not show, since only the
- replayed native payload holds it. With no such URL (a single result, or results that stay encrypted, such as
- xAI's X search) no replay runs and replay evidence stays unknown, so turns replay synthetically. An answer without
- such a URL, or a refusal, is inconclusive; `unsupported` comes only from a 400 naming the replayed content or a new
- call to the tool.
-24. For OpenAI and xAI executors, each source's `snippet` is the answer text its `url_citation` span covers, extended
- to the enclosing sentence; the executor instruction asks for one or two cited sentences per result so the spans
- align. A source without a span has no snippet; Anthropic keeps `cited_text`. Tested against a recorded executor
- response.
-25. Each response has a maximum number of image events (final plus requested partials, plus a small margin) and a
- cumulative decoded-byte budget; exceeding either ends the stream as a provider error. The terminal duplicate is
- still discarded undecoded.
-26. Context-tier thresholds use total context input: input plus cache-read and cache-write tokens.
-27. The proxy endpoint returns a generated image's bytes to Vibey's tool runtime over the local hop. Vibey saves them
- through the same session media sink the native path uses, then builds the `HostedRecord` with the path record.
- The bytes are never persisted in a transcript, and Vibey stays the only writer of session media.
-28. `generate.prompt` is required only for a `completed` record; a `failed` or `incomplete` record may omit it when
- the provider's `revised_prompt` is absent or null.
+| Evidence | `evidence_rules` against recorded served streams and error bodies | a served native web search writes one positive record; an executor call writes one for the executor; `Unsupported tool type` and `Invalid encrypted_content` each write one negative record; overload, 5xx and other 400s write none; a negative record under another wire stamp reads as unknown; a negative record does not expire with age; the clear endpoint removes one (Source, tool)'s records, or every Source's for the tool, and nothing else; an effort refusal does not expire, and clearing it lets the next request at that effort reach the Source |
+| Hop facts | `hosted_tools` resolution | `assumed` from priors with no evidence; `unsupported` with a current negative; a Claude subscription never `assumed`; a translated path never `assumed`; the image enum and default, deterministic |
+| Config | `ModelHubConfig` loader | a 3.2.0 config without the section has every tool on; an rc-era section keeps each tool's `enabled` and ignores the unknown key and fields with a warning; `executor_order` and `default_model` round-trip |
+| Gateway refusal | real gateway + loopback fake engine | a pinned native request refused with `Unsupported tool type` answers 409 with `reason`, and the evidence is written first; admission refuses a declared tool with current negative evidence; a refusal whose evidence write fails still refuses the next native declaration; an Anthropic `web_search_tool_result_error` writes no positive record |
+| Re-render | Vibey loop with a stub gateway | re-resolve after `hosted_unsupported` resends with the function, other native content still pinned; the per-key and per-turn bounds; same facts go portable; an in-flight continuation whose tool turned proxy uses the in-place form; a decrypt 400 on an unpinned request re-renders once without that identity's opaque payloads; a `pause_turn` continuation's `pin_unavailable` still ends `interrupted` |
+| Executor chain | gateway endpoint, stub providers | order from `executor_order` then Source order; failover on 5xx and on a narrow refusal; a mid-stream failure moves on and is metered; a response that never ran the tool ends the chain; a candidate removed during the chain is skipped; `model_not_found` moves on; no candidate gives a `failed` record naming the fix; metering on the executor Source; a Claude subscription is never a candidate |
+| Images | gateway endpoint + Vibey tool runtime, stub endpoints | a model outside the turn's enum is refused; generations and edits per kind; a buffered call over 120 s is not cut; reference images within the per-tool request bound; JPEG requested where allowed; a failure names the alternatives and no other model is called; bytes saved once through the media sink; the path record; no base64 in history |
+| Parsing and replay | adapters and transforms | v1's mapping and replay cases minus native images; an injected `image_generation_call` is ignored like any undeclared item, without decoding |
+| UI | Tools tab, Source chips, tool card | default on; status lines appear only after use; "清除" and "全部清除" on refusals call the clear endpoint; executor order up/down and reset; image models and default; chips without actions; no probe UI |
+| E2E, once per release | real engine + stub upstream | a native web search, a proxied X search, and one `image_generate` per shipped image kind through the shipped engine |
+
+## 15. Known by design
+
+1. **Silent drops are invisible.** A Source that accepts a native declaration but never runs the tool looks like a
+ model that chose not to search, and one that accepts a replayed payload but drops it loses the results' page
+ content. Passive learning cannot see either. The status line simply never shows that Source executing.
+2. **The first refusal costs one request and one cold prefix** per (Source, tool), and again after the record is
+ cleared (§3.5).
+3. **A refusal stays until cleared.** A relay that later starts supporting a tool or an effort keeps getting the
+ proxy function, or keeps being skipped at that effort, until the user clears the refusal, or its config or the
+ engine or Avibe release changes (owner decision: no time limit).
+4. **The executor's lightweight model is a catalog choice.** A Source that does not serve it moves the chain on; the
+ user cannot pick a different executor model in v2.
+5. **A decrypt refusal drops a whole identity's opaque payloads for the turn**, reasoning included, because xAI's
+ refusal does not say which ciphertext failed (§3.5). The turn continues with portable history for that Source.
+6. **An rc-era image opt-out is not carried over.** v1's tool was `image_generation`; v2's is `image_generate`, and the
+ loader treats the old key as unknown rather than mapping it (owner directive: no compatibility code for
+ pre-release state). Only rc testers who turned image generation on and then off are affected; rc4 kept it off
+ unless enabled.
+7. **rc-era state is not migrated** (owner directive): probe evidence carries `basis: probe`, which v2's loader does not
+ accept, so those records are pruned; an rc-era `hosted_tools` section keeps each tool's `enabled`, and its unknown
+ keys and fields are ignored (§3.3); an rc session holding a native `image_generation` block no longer loads its
+ context (§4.2), and its turn ends with the existing localized context-load error ("this session's history can't
+ be loaded; start a new session"), never a raw traceback: ordinary error handling, not a compatibility path.