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(vibey): design hosted tools and the Model Hub capability model (#2545)
Call Whited0b02cb35baa
diff --git a/docs/plans/agent-core-contracts/conversion-tables.md b/docs/plans/agent-core-contracts/conversion-tables.mdindex 9c121e43f..6f9784bec 100644--- a/docs/plans/agent-core-contracts/conversion-tables.md+++ b/docs/plans/agent-core-contracts/conversion-tables.md@@ -640,3 +640,24 @@ Responses terminal states:| `incomplete_details.reason=max_output_tokens` or `length` | `length` || `incomplete_details.reason=content_filter` or `safety` | `safety` || Failed/cancelled | terminal `ProviderError` (classified `unknown` when no provider error code is present) |++## Hosted tools (planned)++Planned by [`../vibey-hosted-tools.md`](../vibey-hosted-tools.md) (Phase 1: `web_search`, `x_search`). These rows+describe the wire mapping the `ai` lane implements with that phase. Until then the adapters ignore hosted items, as+the sections above record, and the Anthropic stop table above still maps `pause_turn` to `stop`.++| Concern | Anthropic Messages | OpenAI Responses (OpenAI, xAI) | OpenAI Chat Completions |+| --- | --- | --- | --- |+| Native declaration (mode from `HopResolution.hosted_tools`) | `{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}` | `{"type": "web_search"}`; xAI also `{"type": "x_search"}`; OpenAI `{"type": "image_generation", "partial_images": 2}`; plus the overlay entry's `include` values (OpenAI web search: `web_search_call.action.sources`) | none. A `google` hop is reached over this Chat form, and the engine translates it to Gemini. |+| Proxy declaration | `{"name": <tool>, "input_schema": <canonical>}` | `{"type": "function", "name": <tool>, "parameters": <canonical>}` | `{"type": "function", "function": {...}}` |+| Native result → `HostedToolBlock` | every item under a declared hosted tool, one block each, in stream order, mapped to a provider-neutral `action` by the rule in `../vibey-hosted-tools.md` §4.2. `server_tool_use` plus its `web_search_tool_result` → `search`; `encrypted_content` only in `native.payload`. | `web_search_call` `search` (`queries[]`, else `query`) / `open_page` / `find_in_page`; xAI `custom_tool_call` `x_keyword_search` / `x_semantic_search` / `x_user_search` / `x_thread_fetch`. The `tco_…` `reasoning` items stay thinking blocks. Unknown items become `other`, never dropped. | — |+| Response-level facts → `AssistantMessage.hosted_summary` | `usage.server_tool_use` counts | xAI `cost_in_usd_ticks` (reported once per response), `server_side_tool_usage_details` counts, and the X-search `url_citation`s as `cited_sources` | — |+| Citations → `TextBlock.citations` | text-block `citations[]` (`web_search_result_location`: `url`, `title`, `cited_text`) | `output_text.annotations[]` of type `url_citation` (`url`, `title`, `start_index`, `end_index`) | — |+| Same-Source replay (target hop is `native.source_id`, same origin, and `hosted_tools[tool].replay` is true now) | `native.payload` blocks verbatim, in place; citations not sent | `native.payload` items verbatim, in place; annotations not sent; never for `image_generation` | — |+| Images | — | `image_generation_call` → file; history and model context hold the text path record (path, revised prompt, size, mode, cost); `result` base64 never stored; duplicate `result` in `response.completed` not decoded; the image-declaring stream gets a 32 MiB line cap | — |+| Other-origin replay | assistant `tool_use(name=<tool>, input=<per-action arguments>)` + user `tool_result(record as text)`, splitting the assistant message; a `failed`/`incomplete` record sets `is_error: true` | `function_call(name=<tool>, arguments)` + `function_call_output(record as text)`; a failed record's text starts `[<tool> failed: <error>]` | assistant `tool_calls` + `tool` message, failure as in Responses |+| Pinning (any protocol) | a request with a native declaration, a `native.payload` or an in-flight continuation carries `x-avibe-pin-source`. A `409` `model_hub_pin_unavailable` / `pin_unavailable` answer is not shown: the same request is rendered again in portable form (proxy declarations, synthetic history, in-place text) and sent unpinned. | same | — |+| Citations at delivery | `TextBlock.citations` → `core/citations.py` builder → Markdown links + Web sidecar | same | — |+| `pause_turn` | not a stop: the adapter re-sends the request with the paused assistant content appended (no new user message), pinned to the paused response's Source (`x-avibe-pin-source`), and keeps streaming as one response, at most 5 continuations. `usage` is the sum of every continuation's counters. | — | — |+| In-flight replay (same turn, pinned Source) | verbatim. On a narrow rejection or `pin_unavailable`, each server block pair is replaced in place by one text block; signed thinking is kept on the same origin. | verbatim | — |diff --git a/docs/plans/agent-core-contracts/cross-provider.md b/docs/plans/agent-core-contracts/cross-provider.mdindex dc6c87539..4bd5039b3 100644--- a/docs/plans/agent-core-contracts/cross-provider.md+++ b/docs/plans/agent-core-contracts/cross-provider.md@@ -13,6 +13,9 @@ cross-provider history tests (MIT).| Tool call | kept; `id` and `signature` as stored | kept without `signature`; `id` normalized to the target's rules (below) || Tool result | kept | `tool_call_id` rewritten through the same id map || Image in a user or tool-result message | kept | kept if the target model accepts images, else `[image: <name or mime>]` |+| Hosted tool block (`hosted_tool`) | when the target hop is `native.source_id`, its origin equals the message's `origin`, and its current replay evidence is positive (`HopResolution.hosted_tools[tool].replay`): `native.payload` verbatim, in place; otherwise as a different origin. `image_generation` blocks always take the different-origin form. | a synthetic call to the same-named tool, plus its result, both rendered from the block's `action` and `record` by the one record-to-text function under the per-action rules of `../vibey-hosted-tools.md` §5. A `failed` or `incomplete` record is an error result (`is_error`, or a leading `[<tool> failed: <error>]` where the protocol has no flag). A `pending` record is the interrupted-call result below. The assistant message is split around the pair. |+| Text block `citations` | not sent | not sent |+| Tool result with `hosted` (a proxied hosted call) | kept, as any tool result | kept, as any tool result |Invariants:@@ -26,3 +29,11 @@ Invariants:`[tool call interrupted; no result recorded]`, with `is_error: true` (C-5 settles most such calls from the job handlefirst).- Responses API requests use `store: false` and never `previous_response_id`.+- Hosted tool blocks (planned, [`../vibey-hosted-tools.md`](../vibey-hosted-tools.md) §5): `native.payload` is an+ opaque provider payload under every rule above, and its replay is further limited to the recorded Source while+ that Source's current replay evidence is positive. The block never stores replay authorization. A different+ origin loses page text: Anthropic returns it only encrypted, and OpenAI and xAI never return it. Within one+ in-flight turn (`pause_turn`, or a client tool result after server tools in the same message), the request is+ pinned to the Source that produced the content, and the content goes back verbatim. This transform is the only+ converter of hosted content. The gateway never rewrites it: a pinned request it cannot serve comes back as+ `pin_unavailable`, and the transform renders the request again in portable form.diff --git a/docs/plans/agent-core-contracts/model-hub-consumer.md b/docs/plans/agent-core-contracts/model-hub-consumer.mdindex e8876c324..82e01135c 100644--- a/docs/plans/agent-core-contracts/model-hub-consumer.md+++ b/docs/plans/agent-core-contracts/model-hub-consumer.md@@ -38,6 +38,35 @@ consumer's requirements, and the Model Hub lane lands the change in both places.the next request targets the primary origin again, so payloads returned by a fallback origin are not replayed if alater request fails over to that same fallback; a provider that then rejects the call surfaces as a provider error.+7. **Hosted tools** (planned, [`../vibey-hosted-tools.md`](../vibey-hosted-tools.md) §3.5).+ - `HopResolution.hosted_tools` names, for each tool the user enabled:+ - the primary hop's `mode` (`native` or `proxy`);+ - for `native`, the wire declaration, which is required exactly then;+ - the executor bound for this turn (`{source_id, model_id}` or `null`), present for every entry whatever the+ mode, because a native request that comes back `pin_unavailable` is re-rendered with the proxy function in the+ same turn. A config change applies from the next turn;+ - `replay`, true only for the primary hop Source's positive replay evidence taken on the current engine and+ probe shape.+ - `native` requires all of these ([`../model-hub-capability-model.md`](../model-hub-capability-model.md) §3):+ - an eligible credential (never a Claude subscription);+ - positive `call` evidence for that (Source, model), taken on the current engine and probe shape;+ - an untranslated path.+ - **The gateway never rewrites hosted content.** Vibey pins every request that carries a native declaration, a+ native hosted payload or an in-flight continuation, with `x-avibe-pin-source`.+ - A pinned request is served only by that Source, with no failover and no recovery wait. The gateway answers HTTP+ 409 `{"type": "error", "error": {"type": "model_hub_pin_unavailable", "code": "pin_unavailable"}}` in three+ cases:+ - the Source cannot be admitted, checked before invoking anything;+ - its attempt ends before model output with a failover-class failure;+ - its attempt ends before model output with an error that a narrow hosted-content evidence rule names.+ - Vibey then renders the same request in portable form and sends it unpinned; it fails over as today.+ - Item 6 (the opaque thinking strip) is unchanged and applies only to unpinned requests.+ - The served-hop report gains `source`, the serving Source id, so that a hosted block's payload is tagged with+ the exact Source; two Sources can share an origin. The parser in `conversion-tables.md` (exactly `provider`,+ `api`, `model` today) changes in the same release, in a coordinated Model Hub contract bump (v12). Native+ hosted mode lands with or after v12. `../vibey-hosted-tools.md` §5 lists the frozen exact-shape contracts that+ the bump edits together.+## 3. Not requiredFailover, credentials, quota, and Source health stay in Model Hub. The agent never contacts a vendor directly.diff --git a/docs/plans/model-hub-capability-model.md b/docs/plans/model-hub-capability-model.mdnew file mode 100644index 000000000..ed5c4b676--- /dev/null+++ b/docs/plans/model-hub-capability-model.md@@ -0,0 +1,284 @@+# 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+[`model-hub-reasoning-tiers.md`](model-hub-reasoning-tiers.md); it does not replace their forwarding rule.++## 1. Problem++The question is "what can this model do on this Source". Two failures from 2026-10-13 show the gaps:++- **Effort `ultra` (#2539).**+ - `vibe/data/backend_models.json` lists `ultra` for `gpt-6-astra`. That list is Codex's model menu, and `ultra`+ is a Codex client mode: the Codex client maps it to a lower wire tier before sending+ ([`model-hub-capability-authority.md`](model-hub-capability-authority.md)).+ - `resolve_reasoning_tiers` (`core/handlers/model_hub/reasoning_tiers.py`) copies that list onto every Source+ model, so Vibey offers `ultra` and sends it literally.+ - An OpenAI API-key relay answers `400 invalid_value … Supported values are: 'none', 'minimal', 'low', 'medium',+ 'high', 'xhigh', and 'max'`. models.dev already lists `low … max` for the model.+- **Hosted tool `x_search`.** The same relay answers `400 Unsupported tool type: x_search`. Model Hub classifies+ `invalid_request_error` as terminal, so a route that falls over to it fails the turn.++Both failures are a claim about a model stood in for a fact about a Source. The model below keeps three kinds of+fact apart and gives each one owner.++## 2. Three layers++| Layer | Scope | Owner and location | Holds | Never holds |+| --- | --- | --- | --- | --- |+| **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 |++Rules:++1. **Base and overlay are priors.** They decide what Avibe offers and shows before anything is known about a Source.+ They never block a request (reasoning-intent decision of 2026-09-08: capability declarations are not an+ allowlist).+2. **Evidence decides routing.** It is the only layer that may change what a hop receives.+3. **The #2505 rule applies to every fact.** Unknown is not negative. Only explicit negative evidence excludes, and+ only positive evidence enables a feature whose failure is terminal.+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+ never wire tiers.+ - A new provider-neutral `providers` section holds what the backend rows cannot: per-provider wire effort+ corrections, hosted tools and prices (§4). Today the loader admits only `claude` and `codex` rows and no+ provider, so the section needs its own loader and schema.+ - No second file is introduced for Vibey.+ - Native backends keep reading their menu from their rows. Vibey and the gateway read wire values and the+ `providers` section.+5. **One owner per derived fact.** Model Hub resolves the layers once, for both the effort menu and hosted-tool+ modes. Vibey only reads `HopResolution`. Only the gateway's classifier writes evidence, and only Model Hub's+ pricing module turns usage into money. No other component re-derives any of these.++## 3. Evidence++### 3.1 Record++One record per (`source_id`, `model_id`, `feature`). Absence of a record is `unknown`. The persisted shape is+below. Its JSON Schema (`model-hub-contracts/capability-evidence.schema.json`) lands with Phase 0, where the store+validates it.++| Field | Rule |+| --- | --- |+| `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) |+| `observed_at` | timestamp |+| `engine` | engine release at that time; 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 |++`observed` evidence is always `unsupported`.++Records live with the Source's runtime state (`model_hub` state dir). They follow Source identity:+`retry.source_identity` covers kind, vendor, protocol, channel, base URL, credential and verification marker.+Changing any of those drops the Source's evidence.++### 3.2 Learning from real errors (negative evidence)++- **Narrow rules, one per feature, in one place:** the gateway's classifier. It sees every upstream error, and+ nothing else writes evidence. A rule maps an upstream error to exactly one (Source, model, feature) only when the+ error names that feature:+ - `invalid_request_error` / `invalid_value` whose message names the request's `reasoning.effort` value → effort;+ - `Unsupported tool type: <type>` for a type the request declared → hosted tool `call`;+ - `Invalid encrypted_content` inside a hosted result block the request replayed → hosted tool `replay`.+- **Generic errors never create evidence.** That covers 5xx, overload, rate limit, auth, and any 400 that does not+ name the feature.+- **What happens to the request.**+ - An effort rule match fails the request as it does today. The next request skips that hop (§3.4).+ - A hosted-content rule match on a pinned request becomes `pin_unavailable`. Vibey re-sends the same request in+ portable form at once (`vibey-hosted-tools.md` §3.5).+- Negative `observed` evidence expires after 7 days. Relays change, and an expired record falls back to the priors.+ A user's re-verify replaces it at once.++### 3.3 Probes and re-verification++- **A probe is a real upstream call.** It costs money (about $0.01–0.05; the 2026-10-13 spike measured it). It+ runs only on an eligible credential, and a Claude subscription Source is never eligible+ (`vibey-hosted-tools.md` §3.4). It runs only on an explicit user action:+ - enabling a hosted tool for a Source (or choosing it as the proxy executor);+ - the Source card's *Re-verify*;+ - confirming one pending re-verification that the UI lists (below).++ A probe never runs as a silent background job.+- **The probe spec belongs to the feature.**+ - Hosted tools: [`vibey-hosted-tools.md`](vibey-hosted-tools.md) §3.2.+ - Efforts: one minimal request at that effort. Only the efforts a user actually selects are ever probed.+- **Probe evidence becomes stale** on an engine upgrade, a probe-shape change, or when it is 30 days old.+ - **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.++### 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 are its Source model's persisted `reasoning_efforts` when their provenance is `user` or `upstream`; otherwise the overlay's `providers` `wire_efforts`; otherwise the backend row's efforts minus its `client_presets` (provenance `catalog`); otherwise models.dev `reasoning_options`. User-authored lists, including free-form names, are never replaced or filtered by a prior; only a catalog-sourced list drops `client_presets`. A tier is omitted only if **every** hop that can serve the model has negative evidence for it. A tier with negative evidence on some hops is shown with "not on: <Source>". |+| 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. |+| Display | §5 |++This fixes #2539 in three places:+- the overlay lists `ultra` in Codex's `client_presets`, so it is not a wire tier for Vibey;+- models.dev's wire list (`low … max`) is the base;+- the relay's real `400 invalid_value` records `ultra: unsupported` for that Source.++Even without the overlay fix, the next request would skip that hop or fail clearly.++## 4. The overlay's `providers` section++The section is keyed by Source vendor (`openai`, `anthropic`, `xai`, …). Each vendor holds a list of model+families, matched by the existing model-id normalization, the first matching prefix winning. A new model of a+family inherits its row. Shape (`vibe/data/backend_models.json`, `providers`; the loader validates it):++```json+"providers": {+ "xai": {"models": [+ {"match": {"prefix": "grok-4"},+ "wire_efforts": null,+ "hosted_tools": {"openai_responses": {+ "web_search": {"declaration": {"type": "web_search"},+ "price": {"unit": "call", "usd_per_1k": 5, "as_of": "2026-10-13", "url": "https://docs.x.ai/developers/pricing"}},+ "x_search": {"declaration": {"type": "x_search"},+ "price": {"unit": "post", "usd_per_1k": 5, "extra": [{"unit": "profile", "usd_per_1k": 10}], "as_of": "2026-10-13", "url": "https://docs.x.ai/developers/pricing"}}}}}+ ]},+ "anthropic": {"models": [+ {"match": {"prefix": "claude-"},+ "hosted_tools": {"anthropic": {+ "web_search": {"declaration": {"type": "web_search_20250305", "name": "web_search"},+ "price": {"unit": "search", "usd_per_1k": 10, "as_of": "2026-10-13", "url": "https://platform.claude.com/docs/en/about-claude/pricing"}}}}}+ ]}+}+```++Fields of one vendor entry. The loader validates them; their JSON Schema lands with Phase 0.++| Field | Rule |+| --- | --- |+| `models[]` | required; ordered, first match wins |+| `match` | exactly one of `prefix` or `id`, non-empty |+| `wire_efforts` | a list of effort names, or `null` to defer to models.dev |+| `hosted_tools` | protocol (`anthropic`, `openai_responses`, `openai_chat`, `google`) → tool (`web_search`, `x_search`, `image_generation`) → `{declaration, price, include?}`. `declaration` and `price` are required, and `declaration` has a `type`. `include` lists Responses `include` values the tool needs (OpenAI web search: `web_search_call.action.sources`). |+| `price` | `unit` (`call`, `search`, `post`, `profile`, `image`), `usd_per_1k` ≥ 0, `as_of` (date) and `url`, all required; optional `extra[]` of `{unit, usd_per_1k}`. Image prices vary by quality and size, so each `image` entry in `extra[]` also carries `quality` and `size`, and pricing selects the entry that matches the declaration that ran. |+- The overlay records what the **provider** offers. Whether a Source (a relay, a subscription) carries it is+ evidence.+- An invalid vendor entry disables that entry with a warning; startup never fails.++## 5. What Models shows per Source++Each model row on a Source detail panel (`SourceDetailPanel`) gets capability chips. They reuse `chips.tsx` badges+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" |++- 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").++## 6. Pricing++### 6.1 What Avibe uses prices for today++- **A valuation only, never a bill** (`core/handlers/model_hub/pricing.py`):+ - "At API price" on the Usage tab and the quota cards;+ - the subscription payback comparison (MH-QUOTA scenarios).+- Prices come from the user's override file `model_hub_prices.json`, then from models.dev's first-party provider+ row.+- Resolution, admission, cooldown and provenance never read a price. Provenance and the usage ledger record tokens+ only.+- **Source billing.** `ModelHubSourceConfig.billing` is `monthly` (subscription) or `metered` (API key)+ (`source.schema.json`). It drives the billing chip, the payback view, and the failover note `entered_metered`. It+ carries no rate.++### 6.2 Where each pricing fact lives++| Fact | Lives in | Status |+| --- | --- | --- |+| Token prices: input, output, cache read, cache write | models.dev base `cost.*`; the user's override file | used |+| One-hour cache write | override file, or 2× input by default (`pricing.py`) | used; models.dev has no field |+| **Context-tier prices** (a higher rate past a context size) | models.dev `cost.tiers[]` with `{"tier": {"type": "context", "size": N}}`, plus the legacy `cost.context_over_200k`. On 2026-10-13: 630 and 517 models (e.g. `gpt-6-astra` above 272K: $20/$75; `grok-4.6` above 200K: $4/$12) | **not used.** `model_price` reads only the flat fields, so valuation understates long-context use. Fix: when a call's input tokens exceed `size`, the tier's rates apply to the whole call, as the vendors bill. The ledger already has per-call input tokens. |+| **Hosted-tool call prices** | overlay `providers.<vendor>.models[].hosted_tools.<protocol>.<tool>.price` (§4): unit, USD per 1,000 units, date and source URL | new. models.dev has none; the open proposal anomalyco/models.dev#8707 adds `cost.web_search = {search, prompt}` (no maintainer response yet) |+| Search-result tokens | the provider's usage (input tokens), priced by the token rows | already counted as input |+| Provider-reported cost | per-call usage, when present: xAI `cost_in_usd_ticks` (USD × 10¹⁰), `server_side_tool_usage_details`; Anthropic `server_tool_use.web_search_requests` | not read today; hosted tools read it (§6.4) |+| Per-Source billing mode | Source config `billing` | used |+| Relay markup or a different relay rate | not representable. A relay's bill is its own; Avibe shows list price and says so | out of scope (no billing system) |++**Hosted-tool list prices on 2026-10-13** (vendor pages; the overlay records each with its date and URL):++| Provider | Tool | Price |+| --- | --- | --- |+| OpenAI | `web_search` | $10 / 1k calls, plus search-content tokens at the model's input rate |+| Anthropic | `web_search` | $10 / 1k searches, plus result tokens as input, which are billed again on later turns while they stay in context |+| xAI | `web_search` | $5 / 1k calls |+| xAI | `x_search` | $5 / 1k posts and $10 / 1k profiles fetched (per-item billing since 2026-09-21) |++### 6.3 Per-Source billing semantics++- **`metered`.**+ - Price = list price, labelled "at API price".+ - When the provider reports the cost in the response (xAI), show that figure, labelled "reported by xAI".+- **`monthly` (subscription).** No per-call charge. Show "included in subscription" rather than a price, and keep+ the at-API-price valuation for payback.+- **A relay** is `metered` at list price. Its bill may differ, and the cost hint says "at API price" so it never+ claims to be the relay's bill.++### 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.++ All of it is computed by the one pricing owner, `pricing.py`. It is stored once per response: as the message's+ `hosted_summary.cost` for native calls, and as `ProxyExecution.cost` for a proxied call, which is its own executor+ response. A provider-reported figure is never copied into individual calls. Neither the+ executor nor an adapter prices anything itself.+2. **Executor choice.** The Tools tab lists the verified executor candidates with their cost hints and billing mode.+ The user picks one; the default is the first verified candidate in Vibey's Source order. Avibe does not+ auto-optimize cost in Phase 1, because relay prices are unknowable.+3. **Usage accounting.** The proxy executor's calls are metered like any gateway call (usage ledger, provenance),+ attributed to the executor Source.++No new billing store, budget, or cap.++## 7. Upstream models.dev++- **Prices:** support anomalyco/models.dev#8707 (`cost.web_search`) with a comment carrying our measured vendor+ units, including xAI's per-post/per-profile `x_search`, which the proposal does not cover. It is worth doing: it+ removes one overlay table, and OpenCode and others read the same data.+- **Availability** (which hosted tools a provider offers per model): a field would help other consumers, but for+ Avibe it only moves a prior. Relays and subscriptions differ from the provider, so evidence stays the truth. Low+ priority; propose it after the overlay has settled for one release.+- Neither proposal blocks Avibe.++## 8. Acceptance properties++1. A fact from models.dev or the overlay never blocks a request or removes a tier on its own. Only evidence does.+2. Only a narrow rule creates negative evidence. The rule names the (Source, model, feature) it learned. A generic+ error creates none.+3. No probe runs without a user action, and every probe action shows its cost before it runs.+4. Changing a Source's identity drops its evidence. An engine upgrade 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.+5. #2539: a Source that rejected `ultra` shows "ultra · not supported on this Source". The next request at `ultra`+ either skips that hop or fails before invocation with `effort_unsupported`, never a provider 400.+6. Valuation applies context tiers when a call's input tokens exceed the tier size. A model with tiers and no flat+ price is still not priced as zero.diff --git a/docs/plans/model-hub-reasoning-intent.md b/docs/plans/model-hub-reasoning-intent.mdindex 045c2fc2e..9b1e4eb45 100644--- a/docs/plans/model-hub-reasoning-intent.md+++ b/docs/plans/model-hub-reasoning-intent.md@@ -20,6 +20,10 @@ subscription OAuth, credential replacement, or routing policy.- Protocol errors keep their existing terminal behavior. No silent fallback orsynthesized effort is added. Historical stripping telemetry remains readable;new resolver attempts do not claim stripping that no longer happens.+- Amendment (planned, [capability model](model-hub-capability-model.md) §3.4):+ the effort is still forwarded unchanged, but a hop with explicit negative+ evidence for that effort is skipped for the request, and a request that no+ hop can serve fails before invocation with `effort_unsupported`.## Proxy engine boundarydiff --git a/docs/plans/vibey-hosted-tools.md b/docs/plans/vibey-hosted-tools.mdnew file mode 100644index 000000000..f81170a98--- /dev/null+++ b/docs/plans/vibey-hosted-tools.md@@ -0,0 +1,755 @@+# Vibey hosted tools++Status: **design**, 2026-10-13, for owner review.+- 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+ pricing.+- Evidence: the runtime spike of 2026-10-13 (40 + 10 upstream calls through the local engine on API-key relay+ Sources). Its tables are summarised where a rule depends on them.++## 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.++## 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.++## 2. Concepts++- **One user-facing tool per capability.** Phase 1 has `web_search` and `x_search`.+- **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.**+ - `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`+ actions and Anthropic's domain filters and `max_uses`.+ - A wider schema would teach the model arguments that no native mode accepts.+ - `x_search` mirrors the only provider that has it. xAI's model calls `x_keyword_search` with+ `{"query", "limit", "mode"}` (observed). The canonical schema is+ `{"query": string, "limit"?: integer, "mode"?: "Latest" | "Top"}`, named after the hosted tool `x_search`.+ `query` accepts X's advanced-search operators (`from:`, `within_time:`).+ - **Evidence that the same name and schema are safe:** a synthetic same-named call in history was accepted even+ 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 pins the probed (Source, model) with `x-avibe-pin-source`, carries the overlay's+ native declaration whatever the current evidence, and allows no failover. Normal turns never receive it.+- **The `call` probe.** The fixed message is "search for 'Avibe local-first agent OS' and reply with the first+ result's URL".+ - **`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").+- **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, followed by "give the URL of the second result you found,+ without searching again".+ - **`verified`:** the answer contains a URL from the first response's results, 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 an answer that does not use the earlier results (a new+ tool call, or no URL from them). Transport acceptance alone is never verification. xAI accepted verbatim+ replay, 3 of 3.+- **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. An engine upgrade 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:++ ```json+ "model_hub": {+ "hosted_tools": {+ "web_search": {"enabled": true, "executor": {"source_id": "src_…", "model_id": "grok-4.6"}},+ "x_search": {"enabled": false, "executor": null}+ }+ }+ ```++ - 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.+ - 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.++## 4. Vibey responsibilities++### 4.1 Request building++| Protocol | Native declaration | Proxy declaration |+| --- | --- | --- |+| `openai_responses` (OpenAI, xAI) | `{"type": "web_search"}`, `{"type": "x_search"}`, `{"type": "image_generation", "partial_images": 2}`, 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`. |++- 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).+- Its four local tools are unchanged (C-7).++### 4.2 Parsing: the C-1 change++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).++**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,+never dropped.++| Provider item | `tool` | `action` |+| --- | --- | --- |+| OpenAI/xAI `web_search_call`, `action.type: search` | `web_search` | `{type: "search", queries[]}`, taken from `action.queries`, else from the deprecated singular `action.query` |+| `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_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`, every field required: `mode: "proxy"`, `executor_origin`,+ `executor_source_id`, `executor_billing`, `cost`. 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.++### 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.+ - **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.+ - **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.++### 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.++**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.++## 5. Replay and conversion++These rules become 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 |+| --- | --- | --- |+| `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. |+| `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`) becomes a line in the result of the+ preceding synthetic call of the same tool in that response, e.g. "opened <url>" or "fetched thread <ref>".+ Without a preceding call, it becomes its own call with `{query: "<action type> <target>"}`.+ - The response's `hosted_summary.cited_sources` are listed once, in the first synthetic result of that tool, as+ "posts cited in the answer".+ - A `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 edits these exact-shape contracts together:**+ - `model-hub-contracts/hop-origin.schema.json`: add `source` (required);+ - `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 ("exactly `provider`, `api`, `model`");+ - `agent-core-contracts/model-hub-consumer.md`, item 4.++ These files are frozen at v11, so this PR states the change and leaves their text alone.++## 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)++### 7.1 The injected tool moves from the engine to the gateway, per caller++- **Today.** The engine injects `{"type": "image_generation", "output_format": "png"}` into every Codex-executor+ request: CPA `ensureImageGenerationTool`, with `disable-image-generation` unset in+ `vibe/model_hub_runtime/config.py`. That covers OpenAI API keys, the ChatGPT subscription and xAI keys, for any+ caller, Claude Code and OpenCode included. GPT calls it from a Vibey request when asked for a picture; the image is+ billed and then dropped.+- **How Codex consumes it today.**+ - Codex maps a hosted `image_generation_call` item to a `TurnItem::ImageGeneration` (`codex-rs/core/src/event_mapping.rs`)+ and emits app-server `imageGeneration` thread items.+ - Avibe's Codex backend persists those items as files: `modules/agents/codex/event_handler.py`+ `_persist_generated_image`, covered by `tests/test_codex_event_handler.py`.+ - Codex's own `image_gen` extension tool is gated to OpenAI-auth providers (`codex-rs/core/src/tools/spec_plan.rs`+ `image_generation_available`). So through Model Hub, the injected hosted tool is Codex's only image path, and it+ must be preserved exactly.+- **Decision (orchestrator, 2026-10-13):**+ 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. The gateway reproduces CPA's injection **only for Codex CLI requests** (`backend == "codex"`), byte for byte,+ under CPA's own conditions:+ - the hop's Source is served by CPA's Codex executor (an `openai_responses` API key or the ChatGPT subscription);+ - the model id does not end in `spark`;+ - the credential is not a ChatGPT free plan, read from the same plan attribute CPA reads;+ - the body's `client_metadata.ws_request_header_x_openai_internal_codex_responses_lite` is not true. The header+ form is not forwarded by the gateway today, so it is not consulted.++ It then appends the same tool to `tools`, or sets `tools` to it when absent. It leaves the body unchanged when+ an `image_generation` tool, or the `image_gen` function or namespace, is already present.+ 3. Vibey declares `image_generation` itself, only when the user's toggle is on.+- **Effect on other backends.** Claude Code and OpenCode requests routed to a Codex-executor Source stop receiving+ the hidden image tool. They could not show the result, so this removes billed images that nobody saw.+- **Rule boundary.** "The gateway never rewrites hosted content" (§3.5) is about Vibey's requests. This injection is+ a compatibility step for one native caller and adds the tool CPA added.+- **Regression tests.**+ - **Gateway, table-driven from CPA's injection cases:** for a Codex request, the fake engine receives exactly the+ bytes CPA would have produced. One row per condition: no tools, other tools, an existing image tool, the+ `image_gen` function and namespace, `spark`, free plan, and lite metadata.+ - **Other backends:** Claude, OpenCode and Vibey requests reach the engine with no image tool unless they declared+ one.+ - The existing Codex image persistence tests stay unchanged.+ - **E2E once per release:** the real engine in passthrough, a stub upstream, a Codex request. The upstream sees+ exactly one image tool and the Codex backend persists the 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". So either the declaration bounds the output (`output_format` and compression), or+ the store also writes a bounded preview and the record names it. The Phase 1 PR picks one and tests it with a+ 6 MB image.+- **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.+ - Partials are previews for the user's display, written to a temporary file and replaced by the final image.+ They never enter history or model context.+- **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: per image, by quality and size. The overlay records the vendor's table with its date+ and URL, and the card shows the reported or list cost.+- **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, the gateway's per-caller injection for Codex, 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. Continuations are bounded, pinned to the paused response's Source, merged into+ one message, and their usage is summed. Past the bound, 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. A Codex CLI request reaches the upstream with exactly the image tool CPA would have injected. No other caller+ gets one unless it declared it.+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.++| 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 summed usage; the pin header; `pin_unavailable` falls back to the in-place text form |+| 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 |+| Image injection | gateway + loopback fake engine | the §7.1 table (CPA's conditions, byte for byte); Claude, OpenCode and Vibey requests get no image tool unless declared; 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`;+ - `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`, `executor_billing` and `cost`.+ - `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` is present exactly for `native`, and includes the overlay entry's `include` values.++**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`. The gateway's Codex image injection is a+ single function covered by the §7.1 table.++**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 prices in the overlay are keyed variants: each `extra[]` entry for unit `image` carries `quality` and+ `size`, and pricing selects the entry that matches the declaration that ran (capability model §4).+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).