Skip to content

armgit / avibe

Public Imported from GitHub
0

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

fix(model_hub): move an id out of a credential's address everywhere it is a key

cyhdcfa6e51e856
diff --git a/core/handlers/model_hub/adapter.py b/core/handlers/model_hub/adapter.py
index 22792ca75..0cef39d58 100644
--- a/core/handlers/model_hub/adapter.py
+++ b/core/handlers/model_hub/adapter.py
@@ -528,6 +528,20 @@ class EngineAdapter(Protocol):
"""
...
+ async def credential_address(self, credential_ref: str) -> str | None:
+ """Report the address outbound calls reach this credential through.
+
+ The engine addresses a credential through the model field and no other,
+ so a call spells ``<address>/<model>``. Custody mints that address and
+ is the only place it is recorded, which makes this the one answer that
+ can *prove* an id an older release stored carries one — as opposed to
+ guessing from its shape and renaming a vendor's own model.
+
+ None when the credential records no address, including when it is gone.
+ A caller that cannot prove ownership must leave the id alone.
+ """
+ ...
+
async def retarget_api_key_credential(
self,
credential_ref: str,
diff --git a/core/handlers/model_hub/address_repair.py b/core/handlers/model_hub/address_repair.py
new file mode 100644
index 000000000..1ad58d6f0
--- /dev/null
+++ b/core/handlers/model_hub/address_repair.py
@@ -0,0 +1,331 @@
+"""Take a credential's address out of ids a release before this one stored.
+
+The engine reaches one credential through the model field of one outbound
+request and through no other field, so a call spells its target
+``<source prefix>/<model>``. That prefix addresses a credential; it is not part
+of what the model is called. Releases before this one persisted what the
+engine's management API answered with — already addressed — so a stored id could
+carry one, and then composition addressed it a second time and the call failed.
+
+Discovery no longer writes one. This is the repair for files that already have
+one, and it runs here rather than at the config load seam for two reasons the
+load seam cannot answer:
+
+- **Ownership must be proven, not guessed.** A config file records no prefix. A
+ repair reading one can only recognise an address by its minted spelling, and
+ that renames an upstream identity which happens to be spelled that way —
+ ``x-ai/grok-4.6-latest`` and ``accounts/fireworks/models/…`` are the product's
+ own counterexamples. Here the caller resolves each Source's credential first
+ and passes the address it actually mints, so membership is the proof.
+- **An id is a join key.** The same id names a Source's inventory row, a route
+ hop, a route key, a backend menu row, a hidden-model entry, and an Agent's
+ checked menu. Renaming one collection alone leaves the rest naming something
+ gone, so every collection moves here, in one payload, computed before
+ anything is written.
+
+Pure: the caller owns resolving credentials and persisting the result.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .identifiers import (
+ model_id_without_credential_address,
+ model_id_without_credential_addresses,
+)
+
+# A repair costs one credential read per Source, so it is worth knowing first
+# whether there is anything to repair. This recognises the minted shape only to
+# decide that — nothing is renamed on its say-so.
+_ADDRESSED_ID = re.compile(r"avibe-[0-9a-f]{24}/")
+
+
+def payload_carries_credential_address(payload: Mapping[str, Any]) -> bool:
+ """Report whether any stored id looks like it still carries an address."""
+
+ return any(_ADDRESSED_ID.match(value) for value in _stored_model_ids(payload))
+
+
+def _stored_model_ids(payload: Mapping[str, Any]) -> Iterator[str]:
+ """Every id a repair would rewrite, in one place so neither can drift."""
+
+ for source in payload.get("sources") or []:
+ if not isinstance(source, dict):
+ continue
+ for model in source.get("models") or []:
+ if isinstance(model, dict) and isinstance(model.get("id"), str):
+ yield model["id"]
+ for agent in (payload.get("agents") or {}).values():
+ if not isinstance(agent, dict):
+ continue
+ for model in agent.get("models") or []:
+ if isinstance(model, dict) and isinstance(model.get("id"), str):
+ yield model["id"]
+ for value in agent.get("removed_model_ids") or []:
+ if isinstance(value, str):
+ yield value
+ menu = agent.get("menu")
+ if isinstance(menu, dict):
+ for value in menu.get("checked") or []:
+ if isinstance(value, str):
+ yield value
+ for requested, route in (agent.get("routes") or {}).items():
+ if isinstance(requested, str):
+ yield requested
+ if not isinstance(route, dict):
+ continue
+ for hop in route.get("hops") or []:
+ if isinstance(hop, dict) and isinstance(hop.get("model_id"), str):
+ yield hop["model_id"]
+
+
+@dataclass(frozen=True)
+class AddressRepair:
+ """What a repair would write, and how much of it there is to report."""
+
+ payload: dict[str, Any]
+ models: int = 0
+ hops: int = 0
+ routes: int = 0
+ menu_entries: int = 0
+
+ @property
+ def changed(self) -> bool:
+ return bool(self.models or self.hops or self.routes or self.menu_entries)
+
+
+def repair_credential_addresses(
+ payload: Mapping[str, Any],
+ addresses: Mapping[str, str],
+) -> AddressRepair:
+ """Rewrite every id carrying one of these Sources' own proven addresses.
+
+ ``addresses`` maps a Source id to the address its credential is reached by.
+ A Source absent from it is left alone entirely — an unresolvable credential
+ proves nothing, and a guess is what this design exists to avoid.
+
+ The payload is one a loaded config produced, so every collection in it has
+ already passed the strict parse: ids are unique before the rename, and any
+ collision seen here is one the rename itself created. Where a repaired id
+ lands on a name already held, the holder stays — it is the row, hop, or
+ route the product has been using, and the repaired one names no identity the
+ holder does not already name.
+ """
+
+ known = frozenset(addresses.values())
+ if not known:
+ return AddressRepair(dict(payload))
+
+ healed: dict[str, Any] = dict(payload)
+ models_moved = 0
+ if isinstance(payload.get("sources"), list):
+ healed_sources: list[Any] = []
+ for source in payload["sources"]:
+ prefix = addresses.get(source.get("id")) if isinstance(source, dict) else None
+ models = source.get("models") if isinstance(source, dict) else None
+ if prefix is None or not isinstance(models, list):
+ healed_sources.append(source)
+ continue
+ healed_models, moved = _healed_rows(models, frozenset({prefix}))
+ models_moved += moved
+ healed_sources.append({**source, "models": healed_models})
+ healed["sources"] = healed_sources
+
+ hops_moved = 0
+ routes_moved = 0
+ menu_entries_moved = 0
+ if not isinstance(payload.get("agents"), dict):
+ return AddressRepair(
+ payload=healed,
+ models=models_moved,
+ )
+ healed_agents: dict[str, Any] = {}
+ for backend, agent in payload["agents"].items():
+ if not isinstance(agent, dict):
+ healed_agents[backend] = agent
+ continue
+ healed_agent = dict(agent)
+
+ # A menu id, a route key, a hidden-model entry and a checked entry each
+ # record no Source. They do not have to: an address names exactly one
+ # credential, and a credential binds to exactly one Source.
+ models = agent.get("models")
+ if isinstance(models, list):
+ healed_models, moved = _healed_rows(models, known)
+ menu_entries_moved += moved
+ healed_agent["models"] = healed_models
+
+ removed = agent.get("removed_model_ids")
+ if isinstance(removed, list):
+ healed_removed, moved = _healed_ids(removed, known)
+ menu_entries_moved += moved
+ healed_agent["removed_model_ids"] = healed_removed
+
+ menu = agent.get("menu")
+ if isinstance(menu, dict) and isinstance(menu.get("checked"), list):
+ healed_checked, moved = _healed_ids(menu["checked"], known)
+ menu_entries_moved += moved
+ healed_agent["menu"] = {**menu, "checked": healed_checked}
+
+ routes = agent.get("routes")
+ if isinstance(routes, dict):
+ healed_routes: dict[str, Any] = {}
+ # Which slots a key that needed no repair claimed, so a later one
+ # cannot demote it just by arriving second.
+ claimed_bare: set[str] = set()
+ for requested, route in routes.items():
+ healed_route = route
+ if isinstance(route, dict) and isinstance(route.get("hops"), list):
+ healed_hops, moved = _healed_hops(route["hops"], addresses)
+ hops_moved += moved
+ healed_route = {**route, "hops": healed_hops}
+ identity = (
+ model_id_without_credential_addresses(requested, known)
+ if isinstance(requested, str)
+ else requested
+ )
+ bare = identity == requested
+ if identity != requested:
+ routes_moved += 1
+ held = healed_routes.get(identity)
+ if held is None:
+ healed_routes[identity] = healed_route
+ if bare:
+ claimed_bare.add(identity)
+ continue
+ # Two keys naming one model. The route the Agent has been
+ # resolving against is the one already spelled bare, so it is
+ # the base and gains only hops it does not already have.
+ if bare and identity not in claimed_bare:
+ healed_routes[identity] = {
+ **healed_route,
+ "hops": _merged_hops(healed_route, held),
+ }
+ claimed_bare.add(identity)
+ continue
+ healed_routes[identity] = {
+ **held,
+ "hops": _merged_hops(held, healed_route),
+ }
+ healed_agent["routes"] = healed_routes
+
+ healed_agents[backend] = healed_agent
+ healed["agents"] = healed_agents
+
+ return AddressRepair(
+ payload=healed,
+ models=models_moved,
+ hops=hops_moved,
+ routes=routes_moved,
+ menu_entries=menu_entries_moved,
+ )
+
+
+def _healed_rows(
+ rows: list[Any],
+ addresses: frozenset[str],
+) -> tuple[list[Any], int]:
+ """Rename each row's id, dropping one that lands on a name already held.
+
+ The row already spelling the bare name wins over one repaired onto it: it
+ is the row the product has been listing and metering, and the repaired one
+ names no model it does not already name. Among two repaired rows meeting on
+ one name, the first wins, which is the policy discovery itself applies.
+ """
+
+ held = {
+ row["id"]
+ for row in rows
+ if isinstance(row, dict)
+ and isinstance(row.get("id"), str)
+ and model_id_without_credential_addresses(row["id"], addresses) == row["id"]
+ }
+ healed: list[Any] = []
+ moved: set[str] = set()
+ count = 0
+ for row in rows:
+ row_id = row.get("id") if isinstance(row, dict) else None
+ if not isinstance(row_id, str):
+ healed.append(row)
+ continue
+ identity = model_id_without_credential_addresses(row_id, addresses)
+ if identity == row_id:
+ healed.append(row)
+ continue
+ count += 1
+ if identity in held or identity in moved:
+ continue
+ moved.add(identity)
+ healed.append({**row, "id": identity})
+ return healed, count
+
+
+def _healed_ids(
+ values: list[Any],
+ addresses: frozenset[str],
+) -> tuple[list[Any], int]:
+ """Rename each id in a flat list, keeping the first of any pair that meets."""
+
+ healed: list[Any] = []
+ seen: set[str] = set()
+ count = 0
+ for value in values:
+ if not isinstance(value, str):
+ healed.append(value)
+ continue
+ identity = model_id_without_credential_addresses(value, addresses)
+ if identity != value:
+ count += 1
+ if identity in seen:
+ continue
+ seen.add(identity)
+ healed.append(identity)
+ return healed, count
+
+
+def _healed_hops(
+ hops: list[Any],
+ addresses: Mapping[str, str],
+) -> tuple[list[Any], int]:
+ """Rename each hop against the address of the Source that hop names."""
+
+ healed: list[Any] = []
+ seen: set[tuple[str, str]] = set()
+ count = 0
+ for hop in hops:
+ if not isinstance(hop, dict):
+ healed.append(hop)
+ continue
+ source_id = hop.get("source_id")
+ model_id = hop.get("model_id")
+ prefix = addresses.get(source_id) if isinstance(source_id, str) else None
+ if prefix is None or not isinstance(model_id, str):
+ healed.append(hop)
+ continue
+ identity = model_id_without_credential_address(model_id, prefix)
+ if identity != model_id:
+ count += 1
+ pair = (source_id, identity)
+ if pair in seen:
+ continue
+ seen.add(pair)
+ healed.append(hop if identity == model_id else {**hop, "model_id": identity})
+ return healed, count
+
+
+def _merged_hops(held: Any, incoming: Any) -> list[Any]:
+ merged = list(held.get("hops") or []) if isinstance(held, dict) else []
+ present = {
+ (hop.get("source_id"), hop.get("model_id"))
+ for hop in merged
+ if isinstance(hop, dict)
+ }
+ for hop in (incoming.get("hops") or []) if isinstance(incoming, dict) else []:
+ if isinstance(hop, dict) and (hop.get("source_id"), hop.get("model_id")) in present:
+ continue
+ merged.append(hop)
+ return merged
diff --git a/core/handlers/model_hub/identifiers.py b/core/handlers/model_hub/identifiers.py
index 37767dc72..21bdacf0e 100644
--- a/core/handlers/model_hub/identifiers.py
+++ b/core/handlers/model_hub/identifiers.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import hashlib
import re
+from typing import Container
# Usage rows shipped with a 200-character readable head. Keep that threshold
# stable even when a later API admits longer model identifiers, or one upgrade
@@ -37,25 +38,49 @@ def model_id_without_credential_address(value: str, prefix: str | None = None) -
not ours to rename. Callers that hold the owning Source or credential always
pass it.
- Without one, the address is recognised by its minted shape. That is for a
- record which stores no prefix of its own to compare against — a config file
- an earlier release wrote — and it is why that path is confined to rows
- discovery produced, which are the only rows an address can have reached.
+ Without one, the address is recognised by its minted shape. That is for the
+ one caller holding a credential whose metadata records no prefix, and it is
+ a fallback: it fails visibly, at the same place this bug did, rather than
+ renaming a vendor's model quietly.
Unwrapping repeatedly rather than once makes the result total: whatever this
returns carries no address, so a caller never has to ask how many one
identity accumulated across releases.
"""
+ if prefix is not None:
+ return model_id_without_credential_addresses(value, (prefix,))
identity = value
while True:
address, separator, remainder = identity.partition("/")
if not separator or not remainder:
return identity
- if prefix is not None:
- if address != prefix:
- return identity
- elif not _CREDENTIAL_ADDRESS_SHAPE.fullmatch(address):
+ if not _CREDENTIAL_ADDRESS_SHAPE.fullmatch(address):
+ return identity
+ identity = remainder
+
+
+def model_id_without_credential_addresses(
+ value: str,
+ addresses: Container[str],
+) -> str:
+ """Return the identity ``value`` names, with no *known* address around it.
+
+ The same removal as above, for a caller holding more than one credential.
+ ``addresses`` are proven addresses — each one minted for a credential this
+ installation holds — so membership is the proof of ownership, and a leading
+ segment that is not one of them belongs to whoever named the model.
+
+ This is what lets an identity be repaired outside the Source that owns it.
+ A backend menu row, a route key, or a hidden-model entry records no Source,
+ but an address names exactly one credential and a credential binds to
+ exactly one Source, so an id carrying a proven address came from there.
+ """
+
+ identity = value
+ while True:
+ address, separator, remainder = identity.partition("/")
+ if not separator or not remainder or address not in addresses:
return identity
identity = remainder
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 42b9430e9..9c56ef555 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -70,6 +70,10 @@ from .adapter import (
make_source_observation,
validate_source_observation,
)
+from .address_repair import (
+ payload_carries_credential_address,
+ repair_credential_addresses,
+)
from .async_owner import await_owned_task
from .catalog_admission import (
admissible_backend_model,
@@ -1199,6 +1203,73 @@ class ModelHubService:
raise ModelHubError("source_create_in_progress", status=409)
self._source_create_nonces.add(client_nonce)
+ async def _repair_credential_addresses(self) -> None:
+ """Take a credential's address out of ids an older release stored.
+
+ Discovery no longer writes one, but a file written before it stopped
+ can still hold an addressed id, and composition then addresses it a
+ second time — the model the user picked resolves to nothing. Every
+ demand for the engine passes here, so an installation upgrading into
+ this release is repaired the first time it needs a model.
+
+ This is the seam because it is the only one where both halves are in
+ hand. The engine state store can prove which address belongs to which
+ Source, so nothing is renamed on the strength of how it is spelled; and
+ the whole config is loaded, so every collection keyed by a model id
+ moves in one write instead of half the joins being left naming
+ something gone. Persisting goes through the same projection owner as
+ any other mutation, so the engine is reconciled with what was written.
+
+ Best effort by design: an id left alone is exactly the state the
+ previous release was already in, which is not worth failing a demand
+ over. The next demand tries again.
+ """
+
+ async with self._mutation_lock:
+ config = self.store.load()
+ payload = config.to_payload()
+ if not payload_carries_credential_address(payload):
+ return
+ addresses: dict[str, str] = {}
+ for source in config.sources:
+ if not source.credential_ref:
+ continue
+ try:
+ address = await self.adapter.credential_address(
+ source.credential_ref
+ )
+ except Exception:
+ # An address that cannot be read proves nothing about this
+ # Source's ids, and a guess is what this design avoids.
+ logger.debug(
+ "model hub: no provable address for source %s", source.id
+ )
+ continue
+ if address:
+ addresses[source.id] = address
+ try:
+ repair = repair_credential_addresses(payload, addresses)
+ if not repair.changed:
+ return
+ await self._commit_synced(
+ config,
+ ModelHubConfig.from_payload(repair.payload),
+ )
+ except Exception:
+ logger.warning(
+ "model hub: could not repair stored credential addresses",
+ exc_info=True,
+ )
+ return
+ logger.info(
+ "model hub: removed credential addresses from stored ids "
+ "(%d source models, %d route hops, %d routes, %d agent menu entries)",
+ repair.models,
+ repair.hops,
+ repair.routes,
+ repair.menu_entries,
+ )
+
async def _sync_sources(self, config: ModelHubConfig, *, force_empty: bool = False) -> None:
bindings = self._bindings(config)
has_hub_sources = any(
@@ -1321,6 +1392,7 @@ class ModelHubService:
async def _prepare_engine_for_demand(self, *, already_synced: bool = False) -> None:
try:
await self._ensure_runtime_dependency()
+ await self._repair_credential_addresses()
if already_synced:
self._engine_preparation_failed = False
return
diff --git a/docs/plans/model-hub-contracts/adapter-interface.py b/docs/plans/model-hub-contracts/adapter-interface.py
index 22792ca75..0cef39d58 100644
--- a/docs/plans/model-hub-contracts/adapter-interface.py
+++ b/docs/plans/model-hub-contracts/adapter-interface.py
@@ -528,6 +528,20 @@ class EngineAdapter(Protocol):
"""
...
+ async def credential_address(self, credential_ref: str) -> str | None:
+ """Report the address outbound calls reach this credential through.
+
+ The engine addresses a credential through the model field and no other,
+ so a call spells ``<address>/<model>``. Custody mints that address and
+ is the only place it is recorded, which makes this the one answer that
+ can *prove* an id an older release stored carries one — as opposed to
+ guessing from its shape and renaming a vendor's own model.
+
+ None when the credential records no address, including when it is gone.
+ A caller that cannot prove ownership must leave the id alone.
+ """
+ ...
+
async def retarget_api_key_credential(
self,
credential_ref: str,
diff --git a/docs/plans/model-hub-credential-address-repair.md b/docs/plans/model-hub-credential-address-repair.md
index bd5f9ce32..30ff4b47f 100644
--- a/docs/plans/model-hub-credential-address-repair.md
+++ b/docs/plans/model-hub-credential-address-repair.md
@@ -23,8 +23,10 @@ PR #2099 closed the boundary the address enters through:
- **Engine state records** (`vibe/model_hub_runtime/state.py`) heal against their
own `SourceRecord.prefix`, re-keying `model_reasoning_efforts` with the ids.
-What remains is **files already written**. This document is the design for
-repairing those.
+What remained was **files already written**. This document is the design for
+repairing those, and the repair ships in the same PR: the sections below are
+what was built, with the two places the implementation diverged from the first
+draft called out where they occur.
## Why the config layer is the wrong place
@@ -51,51 +53,69 @@ two reasons that are both structural, not fixable by a better heuristic:
So the repair needs both halves that the config layer lacks: the credential
(to prove the prefix) and the service (to move every position together).
-## Functional relief that already exists
+## What refresh already covers
-An affected user is not stuck waiting for this. Once #2099 lands, one **refresh
-models** on the Source re-discovers through the fixed boundary and
+One **refresh models** on the Source re-discovers through the fixed boundary and
`_apply_discovered_models` (`service.py:1904`) replaces the inventory rows with
bare-named ones. What refresh does not do is move a route hop or a route key
that already points at an addressed spelling — those are the positions this
-repair owns.
+repair owns, and it owns them without the user having to know to click anything.
## Design
### Where it runs
-A service-level repair, invoked once per Source from the runtime, not a
-config-load rewrite. Shape:
-
-```
-ModelHubService.repair_credential_addresses(source_id) -> RepairOutcome
-```
-
-The runtime resolves the owning prefix through the existing
-`credential_metadata(...)["prefix"]`, exactly as discovery does, and hands the
-service a **proven** prefix. A Source whose credential no longer resolves is
-skipped and reported — never guessed at.
+A service-level repair over the whole config, not a config-load rewrite and not
+a per-Source call. Three pieces:
+
+- `EngineAdapter.credential_address(credential_ref)`
+ (`vibe/model_hub_runtime/adapter.py`) answers the address custody minted for
+ one credential, read from `credential_metadata_if_present(...)["prefix"]` —
+ the same field discovery compares against. `None` when custody has no record,
+ which is the honest answer and means the caller must leave the id alone.
+- `core/handlers/model_hub/address_repair.py` is pure: given a `model_hub`
+ payload and `{source_id: proven_address}`, it returns the repaired payload and
+ the counts. It resolves nothing and writes nothing.
+- `ModelHubService._repair_credential_addresses` joins the two under the
+ mutation lock and persists through `_commit_synced`, the same projection owner
+ every other mutation uses, so the engine is reconciled with what was written.
+
+**Divergence from the first draft.** The draft had the repair take a
+`source_id`. It takes none: a route key, a menu row, a hidden-model entry and a
+checked entry record no Source, so a per-Source repair cannot reach them without
+guessing. Resolving every Source's address first and then rewriting once removes
+the guess — an address names exactly one credential and a credential binds to
+exactly one Source, so an id carrying a proven address came from that Source
+whatever collection it sits in.
### What it rewrites, in one transaction
-Given `(source_id, prefix)`, build the rename map from the source's own rows —
-`{stored_id: model_id_without_credential_address(stored_id, prefix)}`, keeping
-only entries that actually changed — then apply it to every position in one
-config write:
+The addresses are proven first; then every position is rewritten in one config
+write:
| Position | Rule |
| --- | --- |
| `source.models[].id` | Renamed. A row landing on a name another row already holds is dropped; the holder keeps its display name, reasoning efforts, and provenance. |
| `source.models[].reasoning_efforts` and the engine record's `model_reasoning_efforts` | Follow their row. |
-| Route **hops** (`hop.source_id == source_id`) | Renamed only where the map has the spelling. Two hops collapsing onto one pair are merged; a route left with zero hops keeps its key and reports the ordinary unavailable-target path. |
-| Route **keys** (menu ids a route is keyed by) | Renamed only when the key matches a renamed id *and* no route already exists under the bare name; otherwise the routes are merged hop-wise, bare-name-first. |
-| Backend menu rows (`ModelHubBackendModelConfig`) | Renamed only for rows whose origin is `provider` (the origin `agent_model_candidates` produces from inventory) and whose id matches a renamed id. `builtin` / `models_dev` / `manual` rows are never touched. |
+| Route **hops** | Unwrapped against the address of the Source the hop itself names, since a chain crosses Sources and each has its own address. Two hops collapsing onto one `(source_id, model_id)` pair are merged; a route left with zero hops keeps its key and reports the ordinary unavailable-target path. |
+| Route **keys** (menu ids a route is keyed by) | Unwrapped against any proven address. Where that lands on a key another route already holds, the two merge hop-wise behind the key already spelled bare — whichever order the dict happened to list them in. |
+| Backend menu rows (`ModelHubBackendModelConfig`) | Renamed when the id carries *any* proven address. **Divergence from the first draft**, which restricted this to `provider`-origin rows: the proof is the address, not the origin. A `builtin` or `models_dev` id is never addressed, so the restriction excluded nothing real, and it would have left a `manual` row the user pasted an addressed name into broken forever. |
| `removed_model_ids` | Renamed, so a model the user hid stays hidden. |
+| `menu.checked` (opencode) | Renamed, so a model the user ticked stays ticked. |
| Usage ledger keys | **Not** rewritten. See below. |
Everything is computed first and written once, so a partial rename cannot be
persisted.
+Every one of these collections is uniqueness-checked on load, so a rename that
+creates a collision it does not absorb would turn a loadable file into one that
+fails config load — strictly worse than the addressed id it set out to fix. Two
+rules settle every collision: a repaired entry landing on a name already spelled
+bare gives way to the holder (the row the product has been listing, metering and
+resolving against, which names nothing the repaired one does not); and among two
+repaired entries meeting only because the address came off, the first wins,
+which is discovery's own policy.
+
### The ledger is deliberately excluded
An addressed inventory id cannot have produced a ledger row: composition is
@@ -113,39 +133,55 @@ orphans it and a ledger re-key joins this design.
### When it is triggered
-Preference order, cheapest first:
-
-1. **On Source refresh / reachability check** — the runtime already holds the
- credential there, so the repair costs one extra config write and only on a
- Source that actually has addressed rows.
-2. **On engine start, per bound Source** — covers a user who never clicks
- refresh. Guarded by a fast "does any row carry the minted shape" pre-check so
- the common case does no work.
+`ModelHubService._prepare_engine_for_demand`, the single path every demand for
+the engine passes through — startup recovery (`recover_runtime_intent`), a
+source probe, and an invocation all reach it. An installation upgrading into
+this release is therefore repaired the first time it needs a model, without a
+config-load migration and without a one-shot script.
-Not a config-load migration, and not a one-shot script: it must run where the
-credential is resolvable.
+`payload_carries_credential_address` gates it: a cheap walk of the same
+collections the repair rewrites, matching the minted shape. It decides only
+whether to pay for the credential reads — it never renames anything on its own
+say-so, which is the distinction that makes the shape safe to use here and not
+at the config layer.
### Reporting
-The outcome is reported, not silent: the number of rows, hops, keys, and menu
-rows moved, per Source, in the runtime log, and a Source whose credential could
-not be resolved is named so the user can reconnect it.
-
-## Validation plan
-
-- Unit: rename map built from a proven prefix; foreign address left alone;
- upstream slashes (`x-ai/grok-4.6-latest`, `anthropic/claude-sonnet-4`,
- `accounts/fireworks/models/…`) left alone; row-collision precedence; hop
- merge; route-key merge; menu row renamed only for `provider` origin;
- `removed_model_ids` followed.
-- Property: a repaired config must serialize to one this product loads again —
- the failure mode is writing a surviving name twice and refusing the file on
- the next load.
-- Integration: a source whose credential does not resolve is skipped whole, and
- its config bytes are unchanged.
-- Regression (local Incus only): load a snapshot of an affected `config.json` +
- `sources.json`, refresh the Source, and confirm the six subscription models
- become selectable and invocable end to end.
+One log line with the counts moved — source models, route hops, routes, agent
+menu entries. A Source whose credential cannot be resolved is logged at debug
+and skipped whole; its unreachable credential is already surfaced through the
+Source's own state, and the repair declining to touch it leaves exactly the
+state the previous release was in.
+
+The whole repair is best effort: a failure is logged and the demand continues.
+An id left alone is a state the product already tolerates, and the next demand
+tries again.
+
+## Validation
+
+`tests/test_model_hub_credential_address.py`:
+
+- every collection moves together for one id — inventory, hops, route key, menu
+ row, `removed_model_ids`, `menu.checked`;
+- nothing is renamed without proof: an unresolvable Source and a foreign minted
+ address both leave the file alone, alongside the upstream slashes
+ (`x-ai/grok-4.6-latest`, `accounts/fireworks/models/…`);
+- collision precedence both ways — the bare row keeps its place, and two
+ repaired rows meeting here resolve first-wins;
+- two routes meeting on one model merge hop-wise behind the bare key, and a hop
+ is unwrapped against the address of the Source *that hop names*, not the
+ Source whose row it sits under;
+- the terminal property: a repaired config parses again, with no addressed id
+ left anywhere the pre-check can see;
+- custody is what proves an address — the runtime adapter answers the minted
+ prefix for a bound credential and `None` for one it has no record of;
+- end to end through `_prepare_engine_for_demand`: the stored file is repaired
+ and the engine is sent the bare names, and with no provable address the file
+ is left byte-for-byte as the previous release left it.
+
+Still to do before close-out: a local Incus regression on a snapshot of an
+affected `config.json` + `sources.json`, confirming the subscription models
+become selectable and invocable end to end.
## Out of scope
diff --git a/tests/scenario_harness/model_hub.py b/tests/scenario_harness/model_hub.py
index 38daeda91..e493cc121 100644
--- a/tests/scenario_harness/model_hub.py
+++ b/tests/scenario_harness/model_hub.py
@@ -155,6 +155,9 @@ class ModelHubScenarioAdapter:
async def credential_auth_scheme(self, credential_ref: str) -> str | None:
return None
+ async def credential_address(self, credential_ref: str) -> str | None:
+ return None
+
async def provision_transient_credential(
self,
vendor: str,
diff --git a/tests/test_model_hub_credential_address.py b/tests/test_model_hub_credential_address.py
index d0b020560..ab2e944cc 100644
--- a/tests/test_model_hub_credential_address.py
+++ b/tests/test_model_hub_credential_address.py
@@ -17,12 +17,17 @@ every place it is a join key at once. See
``docs/plans/model-hub-credential-address-repair.md``.
"""
+import asyncio
import copy
import json
import pytest
-from config.v2_config import V2Config
+from config.v2_config import ModelHubConfig, V2Config
+from core.handlers.model_hub.address_repair import (
+ payload_carries_credential_address,
+ repair_credential_addresses,
+)
from core.handlers.model_hub.identifiers import (
model_id_without_credential_address,
normalized_model_id,
@@ -31,7 +36,8 @@ from core.handlers.model_hub.identifiers import (
from core.services.settings import default_config
from vibe import api
from core.handlers.model_hub.adapter import SourceBinding
-from vibe.model_hub_runtime.adapter import _discovered_models
+from tests.test_model_hub_api import FakeAdapter, _service
+from vibe.model_hub_runtime.adapter import CLIProxyEngineAdapter, _discovered_models
from vibe.model_hub_runtime.state import EngineStateError, EngineStateStore, SourceRecord
ADDRESS = "avibe-dc0395516c77a0ee4e62e01e"
@@ -437,3 +443,447 @@ def test_the_config_layer_stores_the_name_it_is_given(tmp_path) -> None:
]
hops = loaded.model_hub.agents["claude"].routes["claude-opus-4-6"].hops
assert [(hop.source_id, hop.model_id) for hop in hops] == [(SOURCE_ID, f"{ADDRESS}/gpt-5.5")]
+
+
+# --- The repair for files an earlier release already addressed -------------
+#
+# Config stores the name it is given, so the repair belongs where both halves
+# of it are answerable at once: the runtime can prove which address belongs to
+# which Source, and the whole config is in hand, so every collection keyed by a
+# model id moves together. These tests hold that boundary.
+
+
+def _agent_payload(
+ *,
+ routes: dict | None = None,
+ models: list[dict] | None = None,
+ removed: list[str] | None = None,
+ checked: list[str] | None = None,
+) -> dict:
+ agent: dict = {
+ "backend": "claude",
+ "mode": "hub",
+ "menu_kind": "fixed",
+ "sources": {"order": [SOURCE_ID]},
+ "routes": routes if routes is not None else {},
+ "models": models if models is not None else [],
+ "removed_model_ids": removed if removed is not None else [],
+ }
+ if checked is not None:
+ agent["menu"] = {"view": "featured", "checked": list(checked)}
+ return agent
+
+
+def _hub_payload(
+ models: list[dict],
+ agent: dict | None = None,
+ *,
+ source_id: str = SOURCE_ID,
+) -> dict:
+ return {
+ "sources": [
+ {
+ "id": source_id,
+ "credential_ref": "cred_fixture123",
+ "models": copy.deepcopy(models),
+ }
+ ],
+ "agents": {"claude": agent if agent is not None else _agent_payload()},
+ }
+
+
+def test_the_repair_moves_an_id_in_every_place_it_is_a_join_key() -> None:
+ """One rename, or none. A half-moved id names a model nothing can serve.
+
+ The inventory row is only the first of six collections that key on a model
+ id. Rename it alone and the route pointing at it, the route key the Agent
+ resolves, the menu row the user sees, the checked entry, and the
+ hidden-model list all keep naming something that no longer exists.
+ """
+
+ payload = _hub_payload(
+ [_model_payload(f"{ADDRESS}/gpt-5.5"), _model_payload("x-ai/grok-4.6-latest")],
+ _agent_payload(
+ routes={
+ f"{ADDRESS}/gpt-5.5": {
+ "hops": [{"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"}]
+ }
+ },
+ models=[{"id": f"{ADDRESS}/gpt-5.5", "origin": "provider"}],
+ removed=[f"{ADDRESS}/gpt-6-astra"],
+ checked=[f"{ADDRESS}/gpt-5.5", "x-ai/grok-4.6-latest"],
+ ),
+ )
+
+ repair = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ assert repair.changed
+ agent = repair.payload["agents"]["claude"]
+ assert [model["id"] for model in repair.payload["sources"][0]["models"]] == [
+ "gpt-5.5",
+ "x-ai/grok-4.6-latest",
+ ]
+ assert list(agent["routes"]) == ["gpt-5.5"]
+ assert agent["routes"]["gpt-5.5"]["hops"] == [
+ {"source_id": SOURCE_ID, "model_id": "gpt-5.5"}
+ ]
+ assert [model["id"] for model in agent["models"]] == ["gpt-5.5"]
+ assert agent["removed_model_ids"] == ["gpt-6-astra"]
+ assert agent["menu"]["checked"] == ["gpt-5.5", "x-ai/grok-4.6-latest"]
+ assert (repair.models, repair.hops, repair.routes, repair.menu_entries) == (1, 1, 1, 3)
+
+
+def test_the_repair_renames_nothing_it_cannot_prove_is_an_address() -> None:
+ """Only an address this installation minted for this Source comes off.
+
+ Without the proof, the only thing left to go on is the spelling — and a
+ leading segment that merely looks minted belongs to whoever named the model.
+ A Source whose credential could not be read is therefore left exactly as the
+ previous release left it, which is a state the product already tolerates.
+ """
+
+ models = [
+ _model_payload(f"{OTHER_ADDRESS}/gpt-5.5"),
+ _model_payload("x-ai/grok-4.6-latest"),
+ _model_payload("accounts/fireworks/models/mixtral"),
+ ]
+ payload = _hub_payload(models)
+
+ unprovable = repair_credential_addresses(payload, {})
+ foreign = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ assert not unprovable.changed
+ assert not foreign.changed
+ for result in (unprovable, foreign):
+ assert [model["id"] for model in result.payload["sources"][0]["models"]] == [
+ f"{OTHER_ADDRESS}/gpt-5.5",
+ "x-ai/grok-4.6-latest",
+ "accounts/fireworks/models/mixtral",
+ ]
+
+
+def test_the_repair_keeps_the_row_the_product_has_been_using() -> None:
+ """A repaired row landing on a name already held gives way to the holder.
+
+ Both name one model. The row already spelled bare is the one the tab lists
+ and the ledger meters, and the repaired one carries nothing it does not.
+ """
+
+ payload = _hub_payload(
+ [
+ _model_payload("gpt-5.5", display_name="Kept"),
+ _model_payload(f"{ADDRESS}/gpt-5.5", display_name="Dropped"),
+ _model_payload(f"{ADDRESS}/{ADDRESS}/gpt-5.5", display_name="Also dropped"),
+ ]
+ )
+
+ repair = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ assert [
+ (model["id"], model["display_name"])
+ for model in repair.payload["sources"][0]["models"]
+ ] == [("gpt-5.5", "Kept")]
+ assert repair.models == 2
+
+
+def test_the_repair_keeps_the_first_of_two_rows_that_meet_only_here() -> None:
+ """With no bare row to defer to, first wins — discovery's own policy."""
+
+ payload = _hub_payload(
+ [
+ _model_payload(f"{ADDRESS}/gpt-5.5", display_name="First"),
+ _model_payload(f"{ADDRESS}/{ADDRESS}/gpt-5.5", display_name="Second"),
+ ]
+ )
+
+ repair = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ assert [
+ (model["id"], model["display_name"])
+ for model in repair.payload["sources"][0]["models"]
+ ] == [("gpt-5.5", "First")]
+
+
+def test_the_repair_merges_two_routes_that_meet_on_one_model() -> None:
+ """Two keys, one model. The bare one is what the Agent already resolves.
+
+ So it stays the route, in its own hop order, and gains only the hops the
+ addressed key reached that it did not. A route dict cannot hold the same key
+ twice, and a hop list cannot hold the same pair twice, so both collapse here
+ or the repaired config does not load.
+ """
+
+ payload = _hub_payload(
+ [_model_payload("gpt-5.5")],
+ _agent_payload(
+ routes={
+ f"{ADDRESS}/gpt-5.5": {
+ "hops": [
+ {"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"},
+ {"source_id": "src_backup", "model_id": "gpt-5.5-mini"},
+ ]
+ },
+ "gpt-5.5": {"hops": [{"source_id": SOURCE_ID, "model_id": "gpt-5.5"}]},
+ },
+ ),
+ )
+
+ repair = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ assert list(repair.payload["agents"]["claude"]["routes"]) == ["gpt-5.5"]
+ assert repair.payload["agents"]["claude"]["routes"]["gpt-5.5"]["hops"] == [
+ {"source_id": SOURCE_ID, "model_id": "gpt-5.5"},
+ {"source_id": "src_backup", "model_id": "gpt-5.5-mini"},
+ ]
+
+
+def test_the_repair_unwraps_a_hop_against_the_source_that_hop_names() -> None:
+ """A hop says which Source it reaches, so it is checked against that one.
+
+ A chain crosses Sources, and each Source has its own address. Reading a hop
+ against the wrong one would either miss the address it does carry or strip a
+ name that only looks addressed.
+ """
+
+ payload = _hub_payload(
+ [_model_payload("gpt-5.5")],
+ _agent_payload(
+ routes={
+ "gpt-5.5": {
+ "hops": [
+ {"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"},
+ {"source_id": "src_backup", "model_id": f"{ADDRESS}/gpt-5.5"},
+ {"source_id": SOURCE_ID, "model_id": "gpt-5.5"},
+ ]
+ }
+ },
+ ),
+ )
+
+ repair = repair_credential_addresses(payload, {SOURCE_ID: ADDRESS})
+
+ # The first hop is repaired; the second names a Source this address does not
+ # belong to and is left alone; the third then collides with the first and is
+ # dropped, because a route cannot list one pair twice.
+ assert repair.payload["agents"]["claude"]["routes"]["gpt-5.5"]["hops"] == [
+ {"source_id": SOURCE_ID, "model_id": "gpt-5.5"},
+ {"source_id": "src_backup", "model_id": f"{ADDRESS}/gpt-5.5"},
+ ]
+ assert repair.hops == 1
+
+
+def test_a_repaired_config_still_loads() -> None:
+ """The terminal property: whatever the repair writes must parse again.
+
+ Every collection it touches is uniqueness-checked on load, so a rename that
+ creates a collision it does not absorb turns a loadable file into one that
+ fails config load — strictly worse than the addressed id it set out to fix.
+ """
+
+ hub = _hub_payload(
+ [
+ _model_payload("gpt-5.5"),
+ _model_payload(f"{ADDRESS}/gpt-5.5"),
+ _model_payload(f"{ADDRESS}/gpt-6-astra", "manual"),
+ ],
+ _agent_payload(
+ routes={
+ f"{ADDRESS}/gpt-5.5": {
+ "hops": [
+ {"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"},
+ {"source_id": SOURCE_ID, "model_id": "gpt-5.5"},
+ ]
+ },
+ "gpt-5.5": {"hops": []},
+ },
+ models=[
+ {"id": "gpt-5.5", "origin": "provider"},
+ {"id": f"{ADDRESS}/gpt-5.5", "origin": "provider"},
+ ],
+ removed=[f"{ADDRESS}/gpt-6-astra", "gpt-6-astra"],
+ ),
+ )
+ hub["sources"][0].update(
+ {
+ "kind": "api_key",
+ "vendor": "openai",
+ "display_name": "Fixture",
+ "protocol": "openai_responses",
+ "base_url": None,
+ "supply_channel": "hub",
+ "billing": "metered",
+ "state": {"status": "standby"},
+ }
+ )
+
+ repair = repair_credential_addresses(hub, {SOURCE_ID: ADDRESS})
+ reloaded = ModelHubConfig.from_payload(repair.payload)
+
+ assert repair.changed
+ assert [model.id for model in reloaded.sources[0].models] == ["gpt-5.5", "gpt-6-astra"]
+ agent = reloaded.agents["claude"]
+ assert list(agent.routes) == ["gpt-5.5"]
+ assert [(hop.source_id, hop.model_id) for hop in agent.routes["gpt-5.5"].hops] == [
+ (SOURCE_ID, "gpt-5.5")
+ ]
+ assert [model.id for model in agent.models] == ["gpt-5.5"]
+ assert agent.removed_model_ids == ["gpt-6-astra"]
+ assert not payload_carries_credential_address(repair.payload)
+
+
+ ("hub", "carries"),
+ [
+ (_hub_payload([_model_payload(f"{ADDRESS}/gpt-5.5")]), True),
+ (_hub_payload([_model_payload("x-ai/grok-4.6-latest")]), False),
+ (
+ _hub_payload(
+ [_model_payload("gpt-5.5")],
+ _agent_payload(checked=[f"{OTHER_ADDRESS}/gpt-5.5"]),
+ ),
+ True,
+ ),
+ (
+ _hub_payload(
+ [_model_payload("gpt-5.5")],
+ _agent_payload(removed=[f"{ADDRESS}/gpt-6-astra"]),
+ ),
+ True,
+ ),
+ (
+ _hub_payload(
+ [_model_payload("gpt-5.5")],
+ _agent_payload(
+ routes={
+ "gpt-5.5": {
+ "hops": [
+ {"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"}
+ ]
+ }
+ }
+ ),
+ ),
+ True,
+ ),
+ ({}, False),
+ ],
+)
+def test_the_precheck_sees_every_collection_the_repair_would_rewrite(
+ hub: dict,
+ carries: bool,
+) -> None:
+ """A repair costs a credential read per Source; this decides whether to pay.
+
+ It answers from the minted shape, which is exactly what a rename may not do
+ — so it may only ever say "look closer", never "rename this". A collection
+ it cannot see is one whose addressed id is never noticed at all, so it walks
+ the same list the repair does.
+ """
+
+ assert payload_carries_credential_address(hub) is carries
+
+
+def test_custody_is_what_proves_an_address(tmp_path) -> None:
+ """The one answer that turns a spelling into a fact.
+
+ Custody mints the address and is the only place it is written down. A
+ credential it has no record of yields nothing, which is the honest answer:
+ a caller that cannot prove ownership must leave the id alone.
+ """
+
+ store, credential_ref = _bound_store(tmp_path)
+ adapter = CLIProxyEngineAdapter.__new__(CLIProxyEngineAdapter)
+ adapter.state_store = store
+
+ address = asyncio.run(adapter.credential_address(credential_ref))
+
+ assert address == store.credential_metadata(credential_ref)["prefix"]
+ assert asyncio.run(adapter.credential_address("cred_absent0000")) is None
+
+
+class _AddressingAdapter(FakeAdapter):
+ """An engine that knows which address belongs to which credential."""
+
+ def __init__(self, addresses: dict[str, str]):
+ super().__init__()
+ self.addresses = addresses
+
+ async def credential_address(self, credential_ref):
+ return self.addresses.get(credential_ref)
+
+
+def _addressed_service(tmp_path, addresses: dict[str, str]):
+ service, store, adapter = _service(tmp_path, _AddressingAdapter(addresses))
+ hub = _hub_payload(
+ [_model_payload(f"{ADDRESS}/gpt-5.5"), _model_payload("x-ai/grok-4.6-latest")],
+ _agent_payload(
+ routes={
+ f"{ADDRESS}/gpt-5.5": {
+ "hops": [{"source_id": SOURCE_ID, "model_id": f"{ADDRESS}/gpt-5.5"}]
+ }
+ },
+ models=[{"id": f"{ADDRESS}/gpt-5.5", "origin": "provider"}],
+ ),
+ )
+ hub["sources"][0].update(
+ {
+ "kind": "api_key",
+ "vendor": "openai",
+ "display_name": "Fixture",
+ "protocol": "openai_responses",
+ "base_url": None,
+ "supply_channel": "hub",
+ "billing": "metered",
+ "state": {"status": "standby"},
+ }
+ )
+ store.config = ModelHubConfig.from_payload(hub)
+ return service, store, adapter
+
+
+def test_the_runtime_repairs_a_stored_address_before_the_engine_sees_it(tmp_path) -> None:
+ """An older release's file is healed on the way to the engine, and stays healed.
+
+ This is the seam because it is the only one where both halves are in hand:
+ the engine can prove the address, and the whole config is loaded, so every
+ collection keyed by that id moves in one write. The engine is then sent the
+ repaired projection, so it never sees the addressed spelling and never gets
+ a second address composed onto one — which is the failure this fixes.
+ """
+
+ service, store, adapter = _addressed_service(tmp_path, {"cred_fixture123": ADDRESS})
+
+ asyncio.run(service._prepare_engine_for_demand())
+
+ assert [model.id for model in store.config.sources[0].models] == [
+ "gpt-5.5",
+ "x-ai/grok-4.6-latest",
+ ]
+ agent = store.config.agents["claude"]
+ assert list(agent.routes) == ["gpt-5.5"]
+ assert [(hop.source_id, hop.model_id) for hop in agent.routes["gpt-5.5"].hops] == [
+ (SOURCE_ID, "gpt-5.5")
+ ]
+ assert [model.id for model in agent.models] == ["gpt-5.5"]
+ assert adapter.synced[-1][0].model_ids == ("gpt-5.5", "x-ai/grok-4.6-latest")
+
+
+def test_the_runtime_leaves_an_id_alone_when_the_address_is_unprovable(tmp_path) -> None:
+ """No proof, no rename — the file is left exactly as the last release left it.
+
+ An engine that cannot answer for the credential is the ordinary case during
+ recovery, and a Source whose address is unknown is one whose ids cannot be
+ told apart from a vendor's own slashed name. Guessing there would rename a
+ model that was never addressed, so the repair declines and the startup it
+ runs inside carries on.
+ """
+
+ service, store, adapter = _addressed_service(tmp_path, {})
+
+ asyncio.run(service._prepare_engine_for_demand())
+
+ assert [model.id for model in store.config.sources[0].models] == [
+ f"{ADDRESS}/gpt-5.5",
+ "x-ai/grok-4.6-latest",
+ ]
+ assert list(store.config.agents["claude"].routes) == [f"{ADDRESS}/gpt-5.5"]
diff --git a/vibe/model_hub_runtime/adapter.py b/vibe/model_hub_runtime/adapter.py
index dcac0dbeb..4c6087b2a 100644
--- a/vibe/model_hub_runtime/adapter.py
+++ b/vibe/model_hub_runtime/adapter.py
@@ -1920,6 +1920,14 @@ class CLIProxyEngineAdapter:
async def credential_auth_scheme(self, credential_ref: str) -> str | None:
return await asyncio.to_thread(self.state_store.credential_auth_scheme, credential_ref)
+ async def credential_address(self, credential_ref: str) -> str | None:
+ metadata = await asyncio.to_thread(
+ self.state_store.credential_metadata_if_present,
+ credential_ref,
+ )
+ prefix = (metadata or {}).get("prefix")
+ return prefix if isinstance(prefix, str) and prefix else None
+
async def retarget_api_key_credential(
self,
credential_ref: str,