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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
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.mdindex 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 anallowlist).-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 isbelow, 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 theoverlay'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 notname 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 notan 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 aresponse 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 executorresponse. A provider-reported figure is never copied into individual calls. Neither theexecutor 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 genericerror 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 flatdiff --git a/docs/plans/vibey-hosted-tools.md b/docs/plans/vibey-hosted-tools.mdindex 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 andpricing.- Evidence: the runtime spike of 2026-10-13 (40 + 10 upstream calls through the local engine on API-key relaySources). 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.