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
"""Native-config discovery and transactional Model Hub credential takeover."""
from __future__ import annotations
import asyncio
import base64
import hashlib
import json
import math
import re
from dataclasses import dataclass, field, replace
from datetime import datetime, timezone
from pathlib import Path
from modules.agents.catalog import NATIVE_CLI_BACKENDS, NativeCliBackend, display_name_for_backend
from typing import Any, Awaitable, Callable, Collection, Literal, Mapping, Optional, Protocol, cast
from config.v2_config import (
MODEL_HUB_BACKENDS,
ModelHubConfig,
ModelHubSourceConfig,
ModelHubSourceStateConfig,
)
from core.handlers.model_hub.adapter import (
DiscoveredModel,
OAuthCredentialRejectedError,
)
from core.handlers.model_hub.events import contains_credential_material
from core.handlers.model_hub.identifiers import canonical_model_id
from core.handlers.model_hub.reasoning_tiers import resolve_reasoning_tiers
from core.handlers.model_hub.migration_files import (
claude_settings_paths,
codex_config_paths,
env_reference,
env_references,
native_store_items,
opencode_auth_path,
opencode_config_paths,
plan_native_cleanup,
planned_native_references,
read_native_config,
)
from core.handlers.model_hub.migration_journal import (
NativeFileEdit,
NativeTakeoverJournal,
TakeoverStateError,
)
from core.handlers.model_hub.migration_persisted import PersistedInventory
from vibe.backend_model_catalog import (
backend_model_entries,
bundled_catalog_wire_efforts_by_model,
load_bundled_catalog,
)
from vibe.codex_config import (
read_codex_auth_state,
)
from vibe.native_oauth_store import (
NativeOAuthSnapshot,
apply_keychain_edit,
read_native_oauth,
)
from vibe.model_hub_runtime.api_key_vendors import (
validate_api_key_auth_scheme,
validate_migration_api_key_transport,
)
from vibe.opencode_config import (
get_opencode_custom_provider_adapter,
)
MigrationAction = Literal["import", "controlled_import", "keep_native", "reauth"]
MigrationKind = Literal["api_key", "oauth_native", "opencode_provider"]
_CUSTOM_ENDPOINT_NOTE = "settings.models.source.customEndpoint"
_NATIVE_SUPPLY_NOTE = "settings.models.source.nativeSupply"
_OPENCODE_BUILTIN_PROTOCOLS: dict[
str,
Literal["anthropic", "openai_chat"],
] = {
"deepseek": "openai_chat",
"minimax": "anthropic",
"openrouter": "openai_chat",
}
_OPENCODE_UNSUPPORTED_NATIVE_IDS = {"alibaba-cn", "poe"}
# Pinned CPA ordinary-grant compatibility. Extra native scopes are permitted,
# but the gateway does not promise to retain connector/plugin capabilities.
_OAUTH_CLIENT_IDS = {
"codex": "app_EMoamEEZ73f0CkXaXp7hrann",
"claude": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
}
_OAUTH_REFRESH_SCOPES = {
"codex": frozenset({"openid", "profile", "email"}),
"claude": frozenset({
"user:profile", "user:inference", "user:sessions:claude_code",
"user:mcp_servers", "user:file_upload",
}),
}
class MigrationConflictError(ValueError):
pass
class MigrationCredentialsInvalidError(RuntimeError):
"""Custody transferred, but one or more grants require Hub reauthentication."""
class MigrationReauthorizationRequiredError(RuntimeError):
"""A changed native snapshot cannot prove a new post-takeover OAuth grant."""
class MigrationHost(Protocol):
store: Any
adapter: Any
revocations: Any
_mutation_lock: Any
now: Callable[[], datetime]
migration_home: Optional[Path]
migration_project_roots: Callable[[], tuple[Path, ...]]
migration_journal: NativeTakeoverJournal
migration_blocked_backends: set[str]
migration_guard: Any
_migration_lock: Any
_engine_synced: bool
@staticmethod
def _clone_config(config: ModelHubConfig) -> ModelHubConfig: ...
@staticmethod
def _mark_source_unverified(source: ModelHubSourceConfig) -> None: ...
async def _engine_call(self, awaitable: Awaitable[Any]) -> Any: ...
async def _commit_synced(
self,
previous: ModelHubConfig,
updated: ModelHubConfig,
*,
rollback_on_sync_failure: bool = True,
) -> None: ...
async def _ensure_runtime_dependency(self) -> Any: ...
async def _save_config(self, config: ModelHubConfig) -> ModelHubConfig: ...
async def _seed_vibey(self, config: ModelHubConfig, *, fetch_catalog: bool = True) -> bool: ...
async def _announce_vibey_seed(self) -> None: ...
def _carry_agent_selections(
self, config: ModelHubConfig, backend: Any, *, native_sources: Collection[tuple[str, str]] = (),
fetch_catalog: bool = True,
) -> None: ...
def _reconcile_native_auth(self, backends: tuple[str, ...]) -> None: ...
async def _sync_sources(self, config: ModelHubConfig, *, force_empty: bool = False) -> None: ...
async def _rollback_credential(
self,
source_id: str,
credential_ref: str,
) -> None: ...
async def _provision_oauth_credential(
self,
source_id: str,
vendor: str,
material: Mapping[str, object],
*, on_reserved: Callable[[str], None] | None = None,
) -> str: ...
def _apply_source_placement(
self,
config: ModelHubConfig,
source: ModelHubSourceConfig,
backends: Collection[str] = MODEL_HUB_BACKENDS,
) -> None: ...
def _added_to(self, source_id: str) -> list[dict]: ...
@dataclass(frozen=True)
class NativeManualModel:
id: str
display_name: Optional[str] = None
@dataclass(frozen=True)
class NativeMigrationItem:
id: str
source_id: str
backend: NativeCliBackend
kind: MigrationKind
masked_detail: str
proposed_action: MigrationAction
selected: bool
notes_key: Optional[str]
vendor: str
protocol: Literal[
"anthropic",
"openai_responses",
"openai_chat",
]
display_name: str
base_url: Optional[str] = None
secret: Optional[str] = field(default=None, repr=False)
account_label: Optional[str] = None
native_provider_id: Optional[str] = field(default=None, repr=False)
manual_models: tuple[NativeManualModel, ...] = ()
# Already-masked credential text, produced by the same `mask_credential` the
# producer used for `masked_detail`. Carried as its own field so a client can
# render provider and key as separate elements without re-parsing the
# composed detail string; never holds plaintext.
masked_credential: Optional[str] = None
# Native OAuth material is process-local only. It is converted into the
# engine's auth-file shape before the source is persisted and is never
# serialized in the scan response.
oauth_material: Optional[dict[str, object]] = field(default=None, repr=False)
native_store_edit: Optional[dict[str, object]] = field(default=None, repr=False)
native_store_revision: Optional[str] = field(default=None, repr=False)
# A metadata-only OS-store row represents one selected credential
# container. Its API-key/OAuth components are resolved after consent.
native_store_placeholder: bool = False
# Codex routing (provider, URL, wire API) the store's credential feeds.
native_store_routing: Optional[str] = field(default=None, repr=False)
source_paths: tuple[str, ...] = ()
required_backends: tuple[str, ...] = ()
shell_variables: tuple[str, ...] = field(default=(), repr=False)
shell_auth_variables: tuple[str, ...] = field(default=(), repr=False)
shell_values: tuple[tuple[str, str], ...] = field(default=(), repr=False)
file_snapshots: tuple[NativeFileEdit, ...] = field(default=(), repr=False)
auth_scheme: str | None = field(default=None, repr=False)
receipt_identity: str | None = field(default=None, repr=False)
# The native config file itself cannot be parsed, so the CLI fails before
# any Hub override applies; this row blocks Hub mode, not just import.
config_blocker: bool = field(default=False, repr=False)
# The settings ``env`` field a Claude credential came from; cleanup
# consent is bound to it, not to equal bytes held in another field.
native_field: str | None = field(default=None, repr=False)
def to_payload(self) -> dict[str, object]:
# Presentation metadata is additive: `vendor` and `display_name` let a
# client name and draw the provider instead of inferring identity from
# `backend` (which cannot tell an OpenCode config key from an auth.json
# one). Every pre-existing key keeps its exact value so the broader
# settings migration surface is untouched.
return {
"id": self.id,
"backend": self.backend,
"kind": self.kind,
"masked_detail": self.masked_detail,
"proposed_action": self.proposed_action,
"selected": self.selected,
"notes_key": self.notes_key,
"vendor": self.vendor,
"display_name": self.display_name,
"masked_credential": self.masked_credential,
"source_paths": list(self.source_paths),
"required_backends": list(self.required_backends),
# The backend's native config cannot be parsed, so Hub mode would
# fail every launch: the whole group is blocked, not just this row.
"config_blocker": self.config_blocker,
# An opaque store resolves only after consent and may hold a key.
"may_hold_api_key": self.kind != "oauth_native" or (
self.native_store_placeholder and self.backend == "codex"
),
}
def _stable_suffix(*parts: str) -> str:
identity = "\0".join(parts).encode("utf-8")
return hashlib.sha256(identity).hexdigest()[:16]
def _retained_key_identity(item: NativeMigrationItem) -> str:
"""Name a copied static key independently of the store revision holding it."""
return "key_" + _stable_suffix(
item.backend, item.vendor, item.protocol, item.auth_scheme or "",
item.native_provider_id or "", item.secret or "", item.base_url or "",
)
def _retained_key_fingerprint(item: NativeMigrationItem) -> str:
"""Name a copied static key by backend and material alone, across routes."""
return "keymat_" + _stable_suffix(item.backend, (item.secret or "").strip())
def _retained_copy_live(copy: Mapping[str, str] | None, live_credentials: Mapping[str, object]) -> bool:
"""A kept native key is shadowed only while Hub still holds its exact copy."""
return copy is not None and live_credentials.get(copy["source_id"], None) == copy["credential_ref"]
def _receipt_sources_intact(host: MigrationHost, record: Mapping[str, Any]) -> bool:
"""Whether every Source a completed batch created still holds its credential."""
current = {source.id: source.credential_ref for source in host.store.load().sources}
return all(
source_id in current and current[source_id] == record.get("source_credentials", {}).get(source_id)
for source_id in record["source_ids"]
)
def _ids(
backend: str,
kind: str,
identity: str,
action: MigrationAction,
version: str = "",
) -> tuple[str, str]:
source_id = f"src_{_stable_suffix('source', backend, kind, identity)}"
item_id = f"mig_{_stable_suffix('item', backend, kind, identity, action, version)}"
return item_id, source_id
def _native_model_ids(backend: str) -> tuple[str, ...]:
catalog = load_bundled_catalog()
return tuple(entry["id"] for entry in backend_model_entries(backend, catalog))
def _safe_account_label(value: object) -> Optional[str]:
if not isinstance(value, str):
return None
candidate = value.strip()
if (
not candidate
or len(candidate) > 64
or re.fullmatch(r"[^@\s]+@[^@\s]+", candidate) is None
or contains_credential_material(candidate)
):
return None
return candidate
def _oauth_field(payload: Mapping[str, object], *names: str) -> object:
for name in names:
value = payload.get(name)
if value is not None:
return value
return None
def _oauth_text(payload: Mapping[str, object], *names: str) -> Optional[str]:
value = _oauth_field(payload, *names)
if not isinstance(value, str) or not value.strip():
return None
return value.strip()
def _jwt_claims(token: str | None) -> dict[str, object]:
"""Read local grant metadata, not an authentication or signature verdict."""
if not token:
return {}
parts = token.split(".")
if len(parts) != 3:
return {}
try:
claims = json.loads(base64.urlsafe_b64decode(parts[1] + "=" * (-len(parts[1]) % 4)))
except (ValueError, UnicodeError):
return {}
return claims if isinstance(claims, dict) else {}
def _normalize_oauth_material(
*,
provider: Literal["claude", "codex"],
payload: Mapping[str, object],
account_id: Optional[str] = None,
) -> Optional[dict[str, object]]:
"""Convert native CLI OAuth JSON into the engine auth-file shape."""
nested = payload
if provider == "claude" and isinstance(payload.get("claudeAiOauth"), dict):
nested = cast(Mapping[str, object], payload["claudeAiOauth"])
if provider == "codex" and isinstance(payload.get("tokens"), dict):
nested = cast(Mapping[str, object], payload["tokens"])
# Official native stores often omit client/scope metadata. Their locator
# establishes the ordinary CLI grant; explicit contrary metadata must
# never be discarded and silently replaced with CPA's fixed defaults.
for metadata in (payload, nested):
for name in ("client_id", "clientId"):
if name in metadata and metadata[name] != _OAUTH_CLIENT_IDS[provider]:
return None
for name in ("scope", "scopes"):
if name not in metadata:
continue
scopes = metadata[name]
if isinstance(scopes, str):
granted = set(scopes.split())
elif isinstance(scopes, list) and all(isinstance(value, str) for value in scopes):
granted = set(scopes)
else:
return None
if not _OAUTH_REFRESH_SCOPES[provider].issubset(granted):
return None
access_token = _oauth_text(nested, "access_token", "accessToken")
refresh_token = _oauth_text(nested, "refresh_token", "refreshToken")
id_token = _oauth_text(nested, "id_token", "idToken")
# The gateway must own a refresh-capable grant after takeover. An access
# token without its refresh token would work only until its current expiry,
# then leave the user with a source that cannot be maintained.
if not refresh_token:
return None
material: dict[str, object] = {
"type": provider,
}
for target, value in (
("access_token", access_token),
("refresh_token", refresh_token),
("id_token", id_token),
(
"last_refresh",
_oauth_field(nested, "last_refresh", "lastRefresh")
or _oauth_field(payload, "last_refresh", "lastRefresh"),
),
("email", _oauth_text(nested, "email") or _oauth_text(payload, "email")),
("expired", _oauth_field(nested, "expired")),
):
if value is not None:
material[target] = value
claims = _jwt_claims(id_token)
if provider == "codex":
auth_claims = claims.get("https://api.openai.com/auth")
if not account_id and isinstance(auth_claims, dict):
account_id = _oauth_text(auth_claims, "chatgpt_account_id")
# CPA's importer does not derive the account header from the id token.
if not account_id:
return None
material["account_id"] = account_id
email = _oauth_text(claims, "email")
if email:
material.setdefault("email", email)
if "expired" not in material:
expires_at = _oauth_field(nested, "expiresAt", "expires_at")
if isinstance(expires_at, (int, float)) and not isinstance(expires_at, bool):
# Claude's native expiresAt is epoch milliseconds.
seconds = expires_at / 1000 if "expiresAt" in nested else expires_at
else:
seconds = _jwt_claims(access_token).get("exp")
if isinstance(seconds, (int, float)) and not isinstance(seconds, bool):
try:
material["expired"] = datetime.fromtimestamp(
seconds, tz=timezone.utc
).isoformat()
except (OverflowError, OSError, ValueError):
return None
if provider == "claude":
for target, names in (
("account_uuid", ("account_uuid", "accountUuid")),
("organization_uuid", ("organization_uuid", "organizationUuid")),
("organization_name", ("organization_name", "organizationName")),
("claude_device_ids", ("claude_device_ids", "claudeDeviceIds")),
):
value = _oauth_field(nested, *names)
if value is not None:
material[target] = value
return material
def _read_codex_oauth_material(
auth_data: Mapping[str, object],
) -> Optional[dict[str, object]]:
tokens = auth_data.get("tokens")
if not isinstance(tokens, dict):
return None
account_id: Optional[str] = None
raw_account_id = tokens.get("account_id") or auth_data.get("account_id")
if isinstance(raw_account_id, str) and raw_account_id.strip():
account_id = raw_account_id.strip()
return _normalize_oauth_material(
provider="codex",
payload=auth_data,
account_id=account_id,
)
def _native_store_items(
backend: Literal["claude", "codex"],
snapshot: NativeOAuthSnapshot | None,
*,
mask_credential: Callable[[str], str],
state: Mapping[str, object] | None = None,
source_paths: tuple[str, ...] = (),
) -> list[NativeMigrationItem]:
if snapshot is None:
return []
payload = snapshot.payload or {}
state = state or {}
vendor = "anthropic" if backend == "claude" else "openai"
oauth_protocol = "anthropic" if backend == "claude" else "openai_responses"
material = (
_normalize_oauth_material(provider="claude", payload=payload)
if backend == "claude" else _read_codex_oauth_material(payload)
) if snapshot.exportable else None
secret = _oauth_text(payload, "OPENAI_API_KEY") if backend == "codex" and snapshot.exportable else None
placeholder = payload.get("store") == "keychain" and payload.get("status") == "metadata_only"
blocked = not snapshot.exportable and not placeholder
has_oauth = backend == "claude" or bool(payload.get("tokens"))
if has_oauth and material is None and not placeholder:
blocked = True
primary_id = f"mig_{_stable_suffix(backend, 'native-store', snapshot.revision)}"
items: list[NativeMigrationItem] = []
if has_oauth or placeholder or blocked:
action: MigrationAction = "keep_native" if blocked else "import"
note = _NATIVE_SUPPLY_NOTE
if blocked and payload.get("store") == "file":
reason = "unreadable" if payload.get("status") == "permission_needed" else "config"
note = f"settings.models.migration.blocked.{reason}"
_, source_id = _ids(backend, "oauth_native", "native-store", action)
account = _safe_account_label(material.get("email")) if material else None
items.append(NativeMigrationItem(
id=primary_id, source_id=source_id, backend=backend,
kind="oauth_native", masked_detail=account or "",
proposed_action=action, selected=not blocked,
notes_key=note, vendor=vendor,
protocol=cast(Any, oauth_protocol),
display_name="Claude" if backend == "claude" else "ChatGPT",
account_label=account, oauth_material=material,
native_provider_id=_oauth_text(state, "active_provider_id"),
native_store_edit=snapshot.keychain_edit,
native_store_revision=snapshot.revision,
native_store_placeholder=placeholder,
source_paths=source_paths,
# Codex reads its own auth.json before any Hub routing applies,
# so one it cannot read or parse fails every launch.
config_blocker=(
backend == "codex" and payload.get("store") == "file"
and payload.get("status") in {"invalid", "permission_needed"}
),
))
if secret:
base_url = _oauth_text(state, "base_url")
protocol = "openai_chat" if state.get("wire_api") == "chat" else "openai_responses"
_, source_id = _ids(backend, "api_key", "native-store", "import")
# Metadata-only consent binds this same primary ID for an API-only bag.
item_id = primary_id if not items else f"mig_{_stable_suffix(primary_id, 'api_key')}"
detail = mask_credential(secret)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend=backend, kind="api_key",
masked_detail=detail, proposed_action="import", selected=True,
notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor=vendor, protocol=cast(Any, protocol), display_name="OpenAI",
base_url=base_url, secret=secret, masked_credential=detail,
native_provider_id=_oauth_text(state, "active_provider_id"),
native_store_edit=snapshot.keychain_edit,
native_store_revision=snapshot.revision,
source_paths=source_paths,
))
if backend == "codex":
routing_revision = _stable_suffix(
_oauth_text(state, "base_url") or "",
_oauth_text(state, "wire_api") or "",
_oauth_text(state, "active_provider_id") or "",
)
items = [
replace(
item, id=f"mig_{_stable_suffix(item.id, routing_revision)}",
native_store_routing=routing_revision,
)
for item in items
]
return items
def _blocked_item(
backend: str, identity: str, reason: str = "config", *,
source_paths: tuple[str, ...] = (),
shell_variables: tuple[str, ...] = (),
shell_auth_variables: tuple[str, ...] = (),
config_blocker: bool = False,
) -> NativeMigrationItem:
item_id, source_id = _ids(backend, "api_key", identity, "reauth")
return NativeMigrationItem(
id=item_id, source_id=source_id, backend=cast(Any, backend),
kind="api_key", masked_detail="", proposed_action="reauth",
selected=False, notes_key=f"settings.models.migration.blocked.{reason}",
vendor={"claude": "anthropic", "codex": "openai", "opencode": "opencode"}[backend],
protocol="anthropic" if backend == "claude" else "openai_responses",
display_name=display_name_for_backend(backend),
source_paths=source_paths, shell_variables=shell_variables,
shell_auth_variables=shell_auth_variables, config_blocker=config_blocker,
)
def _native_source_paths(persisted: PersistedInventory, backend: str) -> tuple[str, ...]:
paths = persisted.credential_paths[backend]
return tuple(dict.fromkeys([
*(str(guard.path) for guard in persisted.guards if guard.path in paths and guard.before is not None),
*(str(path) for path in paths if path in persisted.problems),
]))
def _claude_items(
*,
home: Optional[Path],
mask_credential: Callable[[str], str],
allow_secret: bool = False,
project_roots: tuple[Path, ...] = (),
persisted: PersistedInventory,
) -> list[NativeMigrationItem]:
items: list[NativeMigrationItem] = []
for path in claude_settings_paths(home, project_roots):
if path in persisted.problems:
items.append(_blocked_item(
"claude", str(path), persisted.problems[path], source_paths=(str(path),),
config_blocker=True,
))
continue
config = persisted.documents[path]
if config is None:
continue
env = config.get("env", {})
if not isinstance(env, dict):
items.append(_blocked_item(
"claude", str(path), source_paths=(str(path),), config_blocker=True,
))
continue
base_url = _oauth_text(env, "ANTHROPIC_BASE_URL")
api_key = _oauth_text(env, "ANTHROPIC_API_KEY")
if api_key:
item_id, source_id = _ids(
"claude", "api_key", str(path), "import",
_stable_suffix(api_key, base_url or ""),
)
detail = mask_credential(api_key)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend="claude", kind="api_key",
masked_detail=detail, proposed_action="import", selected=True,
notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor="anthropic", protocol="anthropic", display_name="Anthropic",
base_url=base_url, secret=api_key, masked_credential=detail,
source_paths=(str(path),), native_field="ANTHROPIC_API_KEY",
))
if config.get("apiKeyHelper"):
items.append(_blocked_item(
"claude", f"{path}:helper", "helper", source_paths=(str(path),),
))
token = _oauth_text(env, "ANTHROPIC_AUTH_TOKEN")
if token:
try:
scheme = validate_api_key_auth_scheme("anthropic", "anthropic", base_url, token, "bearer")
except ValueError:
items.append(_blocked_item(
"claude", f"{path}:ANTHROPIC_AUTH_TOKEN", "token", source_paths=(str(path),),
))
else:
item_id, source_id = _ids(
"claude", "api_key", f"{path}:ANTHROPIC_AUTH_TOKEN", "import",
_stable_suffix(token, base_url or "", scheme or ""),
)
masked = mask_credential(token)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend="claude", kind="api_key",
masked_detail=masked, proposed_action="import", selected=True,
notes_key=_CUSTOM_ENDPOINT_NOTE, vendor="anthropic", protocol="anthropic",
display_name="Anthropic", base_url=base_url, secret=token,
masked_credential=masked, source_paths=(str(path),), auth_scheme=scheme,
native_field="ANTHROPIC_AUTH_TOKEN",
))
if env.get("CLAUDE_CODE_OAUTH_TOKEN"):
items.append(_blocked_item(
"claude", f"{path}:CLAUDE_CODE_OAUTH_TOKEN", "token", source_paths=(str(path),),
))
items.extend(_native_store_items(
"claude", read_native_oauth("claude", home=home, allow_secret=allow_secret),
mask_credential=mask_credential,
source_paths=_native_source_paths(persisted, "claude"),
))
return items
def _codex_items(
*,
home: Optional[Path],
mask_credential: Callable[[str], str],
allow_secret: bool = False,
project_roots: tuple[Path, ...] = (),
persisted: PersistedInventory,
) -> list[NativeMigrationItem]:
items = _native_store_items(
"codex", read_native_oauth("codex", home=home, allow_secret=allow_secret),
mask_credential=mask_credential, state=read_codex_auth_state(home),
source_paths=_native_source_paths(persisted, "codex"),
)
for path in codex_config_paths(home, project_roots):
if path in persisted.problems:
items.append(_blocked_item(
"codex", str(path), persisted.problems[path], source_paths=(str(path),),
config_blocker=True,
))
continue
config = persisted.documents[path]
if config is None:
continue
providers = config.get("model_providers", {})
# Only the provider map migration reads and rewrites is checked here.
# The rest of the file belongs to the installed CLI, whose accepted
# shapes differ by version, and fails in direct mode alike.
if not isinstance(providers, dict):
items.append(_blocked_item(
"codex", str(path), source_paths=(str(path),), config_blocker=True,
))
continue
for provider_id, provider in providers.items():
if not _codex_provider_well_typed(provider):
# Codex deserializes the whole provider map before any Hub
# override applies, so one malformed entry fails every launch.
items.append(_blocked_item(
"codex", f"{path}:{provider_id}", source_paths=(str(path),),
config_blocker=True,
))
continue
key = _oauth_text(provider, "experimental_bearer_token")
env_key = _oauth_text(provider, "env_key")
headers = provider.get("http_headers", {})
env_headers = provider.get("env_http_headers", {})
names = tuple(dict.fromkeys([
*([env_key] if env_key else []),
*((value for value in env_headers.values() if isinstance(value, str))
if isinstance(env_headers, dict) else ()),
]))
paths = tuple(dict.fromkeys([
str(path), *(source for name in names for source in persisted.resolve(name).paths),
]))
if env_headers or headers:
# Header templates and shell-owned keys cannot be silently
# reinterpreted as an ordinary Authorization bearer grant.
items.append(_blocked_item(
"codex", f"{path}:{provider_id}", "headers",
source_paths=paths, shell_variables=names, shell_auth_variables=names,
))
continue
shell_values: tuple[tuple[str, str], ...] = ()
if env_key:
resolved = persisted.resolve(env_key)
saved_key = resolved.value.strip() if resolved.value is not None else None
if resolved.reason or not saved_key:
items.append(_blocked_item(
"codex", f"{path}:{provider_id}", resolved.reason or "reference",
source_paths=paths, shell_variables=names, shell_auth_variables=names,
))
continue
if key and key != saved_key:
# Two credential mechanisms must not silently discard one.
items.append(_blocked_item(
"codex", f"{path}:{provider_id}", "credential",
source_paths=paths, shell_variables=names, shell_auth_variables=names,
))
continue
key = saved_key
shell_values = ((env_key, cast(str, resolved.value)),)
if not key:
continue
base_url = _oauth_text(provider, "base_url")
protocol = "openai_chat" if provider.get("wire_api") == "chat" else "openai_responses"
item_id, source_id = _ids(
"codex", "api_key", f"{path}:{provider_id}", "import",
_stable_suffix(key, base_url or "", protocol),
)
masked = mask_credential(key)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend="codex", kind="api_key",
masked_detail=masked, proposed_action="import", selected=True,
notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor="openai", protocol=protocol, display_name="OpenAI",
secret=key, base_url=base_url, masked_credential=masked,
native_provider_id=provider_id,
source_paths=paths, shell_variables=names, shell_values=shell_values,
shell_auth_variables=names,
))
return items
def _load_opencode_provider_catalog(persisted: PersistedInventory) -> dict[str, dict[str, Any]]:
payload = persisted.documents.get(persisted.catalog_path) or {}
return {
provider_id.strip().lower(): provider
for provider_id, provider in payload.items()
if isinstance(provider_id, str) and provider_id.strip() and isinstance(provider, dict)
}
def _opencode_protocol(
provider_id: str,
provider_config: dict[str, Any],
catalog_provider: dict[str, Any],
) -> Optional[Literal["anthropic", "openai_responses", "openai_chat"]]:
if provider_id == "anthropic":
return "anthropic"
if provider_id == "openai":
return "openai_responses"
custom_adapter = get_opencode_custom_provider_adapter(provider_id, provider_config)
if custom_adapter == "anthropic-compatible":
return "anthropic"
if custom_adapter == "openai-compatible":
return "openai_chat"
builtin_protocol = _OPENCODE_BUILTIN_PROTOCOLS.get(provider_id)
if builtin_protocol is not None:
return builtin_protocol
npm = provider_config.get("npm") or catalog_provider.get("npm")
if npm == "@ai-sdk/anthropic":
return "anthropic"
if npm == "@ai-sdk/openai":
return "openai_responses"
if npm in {"@ai-sdk/openai-compatible", "@openrouter/ai-sdk-provider"}:
return "openai_chat"
return None
# Every field of Codex's `ModelProviderInfo` (codex-rs/core/config.schema.json),
# by declared type. Codex ignores unknown keys but rejects a known one of the
# wrong type, so the whole table is checked rather than fields one at a time.
_CODEX_PROVIDER_FIELDS: dict[str, str] = {
**dict.fromkeys((
"name", "base_url", "env_key", "env_key_instructions",
"experimental_bearer_token", "model_catalog_url",
), "text"),
**dict.fromkeys(("http_headers", "env_http_headers", "query_params"), "text_map"),
**{field: field for field in ("auth", "aws", "gateway_oauth")},
**dict.fromkeys((
"request_max_retries", "stream_max_retries", "stream_idle_timeout_ms",
"websocket_connect_timeout_ms",
), "count"),
**dict.fromkeys((
"requires_openai_auth", "supports_websockets", "supports_standalone_web_search",
), "flag"),
"wire_api": "wire_api",
}
# The nested tables Codex deserializes (required keys present, known ones of
# their declared type), from the same schema. Unknown keys are ignored: only
# `--strict-config`, which launches never pass, rejects them. A value is a kind name, a
# nested spec, or a tuple of alternative specs (a tagged enum).
_CodexSpec = dict[str, object]
_COMMAND_SPEC: _CodexSpec = {"command": "text", "args": "texts", "timeout_ms": "positive_count"}
_CODEX_NESTED_SPECS: dict[str, tuple[_CodexSpec, frozenset[str]]] = {
"auth": ({
"command": "text", "args": "texts", "cwd": "text",
"refresh_interval_ms": "count", "timeout_ms": "positive_count",
}, frozenset({"command"})),
"aws": ({
"profile": "text", "region": "text",
"auth_refresh": (_COMMAND_SPEC, frozenset({"command"})),
"credential_export": (_COMMAND_SPEC, frozenset({"command"})),
}, frozenset()),
"gateway_oauth": ({
"authorization_url": "text", "client_id": "text", "token_url": "text",
"resource": "text", "scopes": "texts", "redirect_port": "port",
"delivery": (
({"kind": ("header",), "name": "text", "scheme": "text"}, frozenset({"kind", "name"})),
({"kind": ("cookie",), "name": "text"}, frozenset({"kind", "name"})),
),
}, frozenset({"authorization_url", "client_id", "delivery", "token_url"})),
}
def _text_map(value: object) -> bool:
return isinstance(value, dict) and all(
isinstance(key, str) and isinstance(item, str) for key, item in value.items()
)
def _codex_field_well_typed(kind: str, value: object) -> bool:
if kind == "text":
return isinstance(value, str)
if kind == "text_map":
return _text_map(value)
if kind == "count":
# TOML integers are signed 64-bit; Codex rejects anything wider.
return isinstance(value, int) and not isinstance(value, bool) and 0 <= value < 2**63
if kind == "flag":
return isinstance(value, bool)
if kind in _CODEX_NESTED_SPECS:
return _codex_table_well_typed(_CODEX_NESTED_SPECS[kind], value)
# An unknown variant fails deserialization. `chat` stays accepted: older
# CLIs still run it, and migration carries it as openai_chat.
return value in ("chat", "responses")
def _codex_table_well_typed(spec: object, value: object) -> bool:
if isinstance(spec, str):
if spec == "texts":
return isinstance(value, list) and all(isinstance(item, str) for item in value)
if spec in ("positive_count", "port"):
limit = 2**16 if spec == "port" else 2**63
minimum = 1 if spec == "positive_count" else 0
return isinstance(value, int) and not isinstance(value, bool) and minimum <= value < limit
return _codex_field_well_typed(spec, value)
if isinstance(spec, tuple) and spec and isinstance(spec[0], tuple):
# A tagged enum: exactly one variant has to accept the table.
return any(_codex_table_well_typed(variant, value) for variant in spec)
if isinstance(spec, tuple) and len(spec) == 2 and isinstance(spec[0], dict):
fields, required = spec
return (
isinstance(value, dict)
and required <= value.keys()
and all(_codex_table_well_typed(fields[key], item) for key, item in value.items() if key in fields)
)
# A literal-choice tuple, such as a variant tag.
return value in spec
def _codex_provider_well_typed(provider: object) -> bool:
"""Whether Codex can deserialize this ``model_providers`` entry.
A field of the wrong type fails the whole config before any Hub override
applies, so only an absent field or one of its declared type is safe.
"""
return isinstance(provider, dict) and all(
_codex_field_well_typed(kind, provider[field])
for field, kind in _CODEX_PROVIDER_FIELDS.items() if field in provider
)
_OPENCODE_COST = ({
"input": "finite", "output": "finite", "cache_read": "finite", "cache_write": "finite",
}, frozenset({"input", "output"}))
_OPENCODE_MODALITIES = ("modality", "text", "audio", "image", "video", "pdf")
_OPENCODE_MODEL = ({
"id": "text", "name": "text", "family": "text", "release_date": "text",
"attachment": "flag", "reasoning": "flag", "temperature": "flag", "tool_call": "flag",
"experimental": "flag",
"interleaved": ("any", "flag", "text", ({"field": "text"}, frozenset({"field"}))),
"cost": ({**_OPENCODE_COST[0], "context_over_200k": _OPENCODE_COST}, _OPENCODE_COST[1]),
"limit": ({"context": "finite", "input": "finite", "output": "finite"}, frozenset({"context", "output"})),
"modalities": ({"input": _OPENCODE_MODALITIES, "output": _OPENCODE_MODALITIES}, frozenset()),
"status": ("choice", "alpha", "beta", "deprecated", "active"),
"provider": ({"npm": "text", "api": "text"}, frozenset()),
"options": "record",
"headers": "text_map",
"variants": ("values", ({"disabled": "flag"}, frozenset())),
}, frozenset())
_OPENCODE_TIMEOUT = ("any", "positive_count", ("choice", False))
_OPENCODE_PROVIDER = ({
"api": "text", "name": "text", "id": "text", "npm": "text",
"env": "texts", "whitelist": "texts", "blacklist": "texts",
"options": ({
"apiKey": "text", "baseURL": "text", "enterpriseUrl": "text", "setCacheKey": "flag",
"timeout": _OPENCODE_TIMEOUT, "headerTimeout": _OPENCODE_TIMEOUT,
"chunkTimeout": _OPENCODE_TIMEOUT,
}, frozenset()),
"models": ("values", _OPENCODE_MODEL),
}, frozenset())
def _opencode_value_well_typed(spec: object, value: object) -> bool:
"""Check ``value`` against OpenCode's ``ProviderConfig`` schema.
Effect structs drop unknown keys, so only declared fields are checked.
"""
if spec == "text":
return isinstance(value, str)
if spec == "flag":
return isinstance(value, bool)
if spec == "texts":
return isinstance(value, list) and all(isinstance(item, str) for item in value)
if spec == "text_map":
return _text_map(value)
if spec == "record":
return isinstance(value, dict)
if spec == "finite":
return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
if spec == "positive_count":
# JSON has one number type; `1.0` is the integer 1 to OpenCode.
return (
isinstance(value, (int, float)) and not isinstance(value, bool)
and math.isfinite(value) and value == int(value) and value > 0
)
kind = spec[0] if isinstance(spec, tuple) else None
if kind == "any":
return any(_opencode_value_well_typed(variant, value) for variant in spec[1:])
if kind == "choice":
return any(value is choice or (type(value) is type(choice) and value == choice) for choice in spec[1:])
if kind == "modality":
return isinstance(value, list) and all(item in spec[1:] for item in value)
if kind == "values":
return isinstance(value, dict) and all(_opencode_value_well_typed(spec[1], item) for item in value.values())
fields, required = cast(tuple[dict[str, object], frozenset[str]], spec)
return (
isinstance(value, dict)
and required <= value.keys()
and all(_opencode_value_well_typed(fields[key], item) for key, item in value.items() if key in fields)
)
def _opencode_provider_well_typed(provider: object) -> bool:
"""Whether OpenCode's config schema accepts this ``provider`` entry.
OpenCode validates the whole file on start, so a malformed typed field
fails every launch, Hub-owned or not.
"""
return _opencode_value_well_typed(_OPENCODE_PROVIDER, provider)
def _opencode_manual_models(
provider_config: dict[str, Any],
) -> tuple[NativeManualModel, ...]:
raw_models = provider_config.get("models")
if not isinstance(raw_models, dict):
return ()
models: list[NativeManualModel] = []
for model_id, model_config in raw_models.items():
model_id = canonical_model_id(model_id)
if model_id is None or contains_credential_material(model_id):
continue
raw_name = model_config.get("name") if isinstance(model_config, dict) else None
display_name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else None
if display_name and contains_credential_material(display_name):
display_name = None
models.append(
NativeManualModel(
id=model_id,
display_name=display_name,
)
)
return tuple(models)
def _opencode_plaintext_key(value: object) -> Optional[str]:
if not isinstance(value, str) or not value.strip():
return None
candidate = value.strip()
if "{env:" in candidate or "{file:" in candidate:
return None
return candidate
def _opencode_items(
*,
home: Optional[Path],
mask_credential: Callable[[str], str],
project_roots: tuple[Path, ...] = (),
persisted: PersistedInventory,
) -> list[NativeMigrationItem]:
items: list[NativeMigrationItem] = []
try:
auth_entries = read_native_config(opencode_auth_path(home)) or {}
except (TakeoverStateError, OSError):
# Hub mode cannot prove what an unreadable auth map would shadow, so
# it blocks; config layers still surface their own rows beside it.
auth_entries = {}
items.append(_blocked_item(
"opencode", "auth-file", "unreadable",
source_paths=(str(opencode_auth_path(home)),), config_blocker=True,
))
provider_catalog = _load_opencode_provider_catalog(persisted)
seen_providers: set[str] = set()
for path in opencode_config_paths(home, project_roots):
if path in persisted.problems:
items.append(_blocked_item(
"opencode", str(path), persisted.problems[path], source_paths=(str(path),),
config_blocker=True,
))
continue
config = persisted.documents[path]
if config is None:
continue
provider_configs = config.get("provider", {})
if not isinstance(provider_configs, dict):
items.append(_blocked_item(
"opencode", str(path), source_paths=(str(path),), config_blocker=True,
))
continue
seen_providers.update(provider_configs)
relevant_auth = {key: value for key, value in auth_entries.items() if key in provider_configs}
items.extend(_opencode_candidates(
provider_configs, relevant_auth, provider_catalog, str(path), mask_credential,
persisted=persisted, auth_path=opencode_auth_path(home),
))
unseen_auth = {key: value for key, value in auth_entries.items() if key not in seen_providers}
items.extend(_opencode_candidates(
{}, unseen_auth, provider_catalog, str(opencode_auth_path(home)), mask_credential,
persisted=persisted, auth_path=opencode_auth_path(home),
))
return items
def _opencode_candidates(
provider_configs: dict, auth_entries: dict, provider_catalog: dict,
locator: str, mask_credential: Callable[[str], str],
*, persisted: PersistedInventory, auth_path: Path,
) -> list[NativeMigrationItem]:
provider_ids = set(provider_configs) | set(auth_entries)
items: list[NativeMigrationItem] = []
for provider_id in sorted(provider_ids):
paths = (locator,)
names: tuple[str, ...] = ()
auth_names: tuple[str, ...] = ()
def blocked(
identity: str, reason: str = "config", *, config_blocker: bool = False,
) -> NativeMigrationItem:
return _blocked_item(
"opencode", identity, reason, source_paths=paths, shell_variables=names,
shell_auth_variables=auth_names, config_blocker=config_blocker,
)
if (
not isinstance(provider_id, str) or not provider_id
or len(provider_id) > 64
or any(char not in "abcdefghijklmnopqrstuvwxyz0123456789_.-" for char in provider_id)
or not provider_id[0].isalnum()
or contains_credential_material(provider_id)
):
items.append(blocked(f"{locator}:invalid-provider"))
continue
provider_config = provider_configs.get(provider_id, {})
if not _opencode_provider_well_typed(provider_config):
# OpenCode validates the whole provider map before any Hub
# override applies, so one malformed entry fails every launch.
items.append(blocked(f"{locator}:{provider_id}", config_blocker=True))
continue
options = provider_config.get("options")
if not isinstance(options, dict):
options = {}
key_setting = options.get("apiKey")
names = env_references(options)
auth_names = tuple(dict.fromkeys([
*env_references(key_setting), *env_references(options.get("headers")),
]))
paths = tuple(dict.fromkeys([
locator, *(source for name in names for source in persisted.resolve(name).paths),
*([str(auth_path)] if provider_id in auth_entries else []),
]))
if options.get("headers"):
items.append(blocked(f"{locator}:{provider_id}:headers", "headers"))
continue
shell_values: list[tuple[str, str]] = []
config_key = _opencode_plaintext_key(key_setting)
auth_entry = auth_entries.get(provider_id, {})
if not isinstance(auth_entry, dict):
items.append(blocked(f"{locator}:{provider_id}"))
continue
auth_key = (
_opencode_plaintext_key(auth_entry.get("key"))
if auth_entry.get("type") == "api"
else None
)
key_name = env_reference(key_setting)
if key_name:
resolved = persisted.resolve(key_name)
config_key = (resolved.value.strip() or None) if resolved.value is not None else None
if resolved.reason or (not config_key and not auth_key):
items.append(blocked(
f"{locator}:{provider_id}:key-reference", resolved.reason or "reference",
))
continue
if config_key:
shell_values.append((key_name, cast(str, resolved.value)))
elif isinstance(key_setting, str) and ("{env:" in key_setting or "{file:" in key_setting):
items.append(blocked(f"{locator}:{provider_id}:key-reference", "reference"))
continue
secret = config_key or auth_key
if secret is None:
if options.get("apiKey") or auth_entry:
items.append(blocked(f"{locator}:{provider_id}", "credential"))
continue
raw_base_url = options.get("baseURL")
base_url = raw_base_url.strip() if isinstance(raw_base_url, str) and raw_base_url.strip() else None
base_name = env_reference(raw_base_url)
if base_name:
resolved = persisted.resolve(base_name)
if resolved.reason or not resolved.value:
items.append(blocked(
f"{locator}:{provider_id}:base-reference", resolved.reason or "reference",
))
continue
base_url = resolved.value
shell_values.append((base_name, base_url))
elif base_url and ("{env:" in base_url or "{file:" in base_url):
items.append(blocked(f"{locator}:{provider_id}:base-reference", "reference"))
continue
catalog_provider = provider_catalog.get(provider_id, {})
if base_url is None:
catalog_api = catalog_provider.get("api")
if isinstance(catalog_api, str) and catalog_api.strip():
base_url = catalog_api.strip()
paths = tuple(dict.fromkeys([*paths, str(persisted.catalog_path)]))
protocol = _opencode_protocol(provider_id, provider_config, catalog_provider)
if protocol != _opencode_protocol(provider_id, provider_config, {}):
paths = tuple(dict.fromkeys([*paths, str(persisted.catalog_path)]))
if (
protocol is None or provider_id in _OPENCODE_UNSUPPORTED_NATIVE_IDS
or (base_url is None and provider_id not in {"anthropic", "openai"})
or (auth_entry and auth_entry.get("type") != "api")
):
items.append(blocked(f"{locator}:{provider_id}", "credential"))
continue
manual_models = _opencode_manual_models(provider_config)
action: MigrationAction = "import"
item_id, source_id = _ids(
"opencode",
"opencode_provider",
f"{provider_id}:{locator}",
action,
_stable_suffix(
secret,
base_url or "",
protocol,
*(f"{model.id}\0{model.display_name or ''}" for model in manual_models),
),
)
masked_secret = mask_credential(secret)
detail = f"{provider_id} · {masked_secret}"
items.append(
NativeMigrationItem(
id=item_id,
source_id=source_id,
backend="opencode",
kind="opencode_provider",
masked_detail=detail,
proposed_action=action,
selected=True,
notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor=provider_id,
protocol=protocol,
display_name=provider_id,
base_url=base_url,
secret=secret,
manual_models=manual_models,
masked_credential=masked_secret,
source_paths=paths, shell_variables=names, shell_values=tuple(shell_values),
shell_auth_variables=auth_names,
)
)
if auth_key and auth_key != secret:
# Preserve both settings and auth-store keys, even when one is
# currently shadowed. Cleanup cannot discard an unimported account.
alternate = items[-1]
masked = mask_credential(auth_key)
items.append(replace(
alternate, id=f"mig_{_stable_suffix(alternate.id, auth_key)}",
source_id=f"src_{_stable_suffix(alternate.source_id, auth_key)}",
secret=auth_key, masked_detail=f"{provider_id} · {masked}",
masked_credential=masked,
))
return items
def _shell_items(
persisted: PersistedInventory, mask_credential: Callable[[str], str],
native_items: list[NativeMigrationItem],
) -> list[NativeMigrationItem]:
"""Import literal credentials only with a single, persisted target."""
items: list[NativeMigrationItem] = []
specs = (
("claude", "ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "anthropic", "anthropic"),
("claude", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "anthropic", "anthropic"),
("claude", "CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_BASE_URL", "anthropic", "anthropic"),
("codex", "OPENAI_API_KEY", "OPENAI_BASE_URL", "openai", "openai_responses"),
("codex", "CODEX_API_KEY", "OPENAI_BASE_URL", "openai", "openai_responses"),
("opencode", "OPENROUTER_API_KEY", None, "openrouter", "openai_chat"),
)
for backend, name, base_name, vendor, protocol in specs:
if any(item.backend == backend and name in item.shell_auth_variables for item in native_items):
# A native provider reference owns the target and transport.
continue
value = persisted.resolve(name)
# Use the same canonical API-key bytes as proof, reuse and custody.
# The original assignment remains separate for exact native cleanup.
secret = value.value.strip() if value.value is not None else None
if not value.paths or (not secret and not value.reason):
continue
base = persisted.resolve(base_name) if base_name else None
names = (name, *((base_name,) if base and base.paths else ()))
paths = tuple(dict.fromkeys([*value.paths, *(base.paths if base else ())]))
reason = value.reason or (base.reason if base else None)
base_url = base.value if base else None
if base_url and any(
profile.values.get(name) and profile.values.get(base_name) != base_url
for profile in persisted.profiles
):
# A login shell and an interactive shell need not read the same
# profiles. A key cannot inherit a guessed target from another one.
reason = reason or "ambiguous_shell"
scheme = None
if name == "CLAUDE_CODE_OAUTH_TOKEN":
reason = reason or "token"
elif name == "ANTHROPIC_AUTH_TOKEN" and secret and not reason:
try:
scheme = validate_api_key_auth_scheme(
vendor, protocol, base_url, secret, "bearer",
)
except ValueError:
reason = "token"
if reason or not secret:
items.append(_blocked_item(
backend, f"shell:{name}", reason or "reference",
source_paths=paths, shell_variables=names, shell_auth_variables=(name,),
))
continue
if vendor == "openrouter":
base_url = "https://openrouter.ai/api/v1"
kind = "opencode_provider" if backend == "opencode" else "api_key"
item_id, source_id = _ids(
backend, kind, f"shell:{name}", "import",
_stable_suffix(secret, base_url or "", scheme or ""),
)
masked = mask_credential(secret)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend=cast(Any, backend),
kind=cast(Any, kind), masked_detail=masked, proposed_action="import",
selected=True, notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor=vendor, protocol=cast(Any, protocol), display_name=vendor,
base_url=base_url, secret=secret, masked_credential=masked,
source_paths=paths, shell_variables=names,
shell_auth_variables=(name,),
shell_values=(
(name, cast(str, value.value)),
*(((base_name, base_url),) if base and base.value else ()),
),
auth_scheme=scheme,
))
return items
def _bind_persisted_inventory(
items: list[NativeMigrationItem], persisted: PersistedInventory,
) -> list[NativeMigrationItem]:
"""Consent includes all consumers of any shell assignment being removed."""
dependencies: dict[str, set[tuple[str, str]]] = {}
for item in items:
dependencies.setdefault(item.backend, set()).update(
(path, name) for name in item.shell_variables
for path in persisted.resolve(name).paths
)
for backend in dependencies:
# Unsupported providers still consume their saved references. A
# selectable peer cannot erase that source by omitting a blocked row.
dependencies[backend].update(
(path, name) for name in persisted.references[backend]
for path in persisted.resolve(name).paths
)
linked = {backend: {backend} for backend in dependencies}
for backend, values in dependencies.items():
for other, other_values in dependencies.items():
if values & other_values:
linked[backend].add(other)
for _ in linked:
for backend in linked:
linked[backend].update(
member for other in tuple(linked[backend]) for member in linked[other]
)
config_paths = set().union(*persisted.backend_paths.values())
unknown_consumers = [
row for row in items
if row.notes_key in {
"settings.models.migration.blocked.config",
"settings.models.migration.blocked.unreadable",
}
and any(Path(path) in config_paths for path in row.source_paths)
]
result = []
for item in items:
closure = tuple(sorted(linked[item.backend]))
shared = any(dependencies[backend] for backend in closure)
if shared and unknown_consumers and item.proposed_action == "import":
item = replace(
item, proposed_action="reauth", selected=False,
notes_key=unknown_consumers[0].notes_key,
source_paths=tuple(dict.fromkeys([
*item.source_paths,
*(path for row in unknown_consumers for path in row.source_paths),
])),
)
guards = persisted.snapshots(item.backend, shared=shared)
revision = persisted.revision(guards)
dependency_revision = _stable_suffix(
*closure,
*(f"{backend}\0{path}\0{name}" for backend in closure
for path, name in sorted(dependencies[backend])),
)
result.append(replace(
item,
id=f"mig_{_stable_suffix(item.id, revision, dependency_revision, item.auth_scheme or '')}",
required_backends=closure if len(closure) > 1 else (),
file_snapshots=guards,
))
# A read concurrent with discovery must never bind a different before image.
for guard in dict.fromkeys(guard for item in result for guard in item.file_snapshots):
guard.check()
return result
def _deduplicate_opencode_items(
items: list[NativeMigrationItem],
validate_base_url: Callable[[object], Optional[str]] | None,
) -> list[NativeMigrationItem]:
"""One logical credential/target, with consent covering every native copy."""
groups: dict[tuple[str, str, str | None, str, str | None], list[NativeMigrationItem]] = {}
for item in items:
if item.kind == "opencode_provider" and item.proposed_action == "import" and item.secret:
target = validate_base_url(item.base_url) if validate_base_url else item.base_url
groups.setdefault((item.vendor, item.protocol, target, item.secret, item.auth_scheme), []).append(item)
replacements: dict[str, NativeMigrationItem] = {}
duplicates: set[str] = set()
for group in groups.values():
if len(group) < 2:
continue
first = group[0]
models: dict[str, NativeManualModel] = {}
for item in group:
for model in item.manual_models:
# Keep the complete model union; the later configuration layer
# supplies a label when the same model is named in both.
models[model.id] = model
# Layer order also owns repeated model labels, so it is consent-bound.
revision = _stable_suffix(*(item.id for item in group))
replacements[first.id] = replace(
first, id=f"mig_{revision}", source_id=f"src_{revision}",
manual_models=tuple(models.values()),
source_paths=tuple(dict.fromkeys(path for item in group for path in item.source_paths)),
shell_variables=tuple(dict.fromkeys(name for item in group for name in item.shell_variables)),
shell_auth_variables=tuple(dict.fromkeys(
name for item in group for name in item.shell_auth_variables
)),
shell_values=tuple(dict.fromkeys(pair for item in group for pair in item.shell_values)),
)
duplicates.update(item.id for item in group[1:])
return [replacements.get(item.id, item) for item in items if item.id not in duplicates]
def _require_native_api_key_transport(item: NativeMigrationItem) -> None:
if item.kind == "oauth_native":
return
try:
validate_migration_api_key_transport(
item.vendor, item.protocol, item.base_url, item.secret, item.auth_scheme,
)
except ValueError:
raise MigrationConflictError from None
def _bearer_transport(item: NativeMigrationItem) -> NativeMigrationItem | None:
"""Carry a custom-endpoint Anthropic key over as the Bearer the engine sends.
The pinned engine sends ``x-api-key`` only to the official origin. Custom
endpoints get Bearer. Migration records that transport without contacting the
endpoint; normal Gateway requests report whether it accepts the credential.
"""
if item.kind == "oauth_native" or item.protocol != "anthropic" or item.auth_scheme is not None:
return None
candidate = replace(item, auth_scheme="bearer")
try:
_require_native_api_key_transport(candidate)
except MigrationConflictError:
return None
return candidate
def scan_native_configs(
config: ModelHubConfig,
*,
mask_credential: Callable[[str], str],
home: Optional[Path] = None,
validate_base_url: Optional[Callable[[object], Optional[str]]] = None,
legacy_auth: Mapping[str, Mapping[str, object]] | None = None,
secret_backends: tuple[str, ...] = (),
project_roots: tuple[Path, ...] = (),
clean_native_stores: Mapping[str, str] | None = None,
retained_native_ids: Mapping[str, Mapping[str, str]] | None = None,
) -> list[NativeMigrationItem]:
"""Read native stores without modifying or deleting any path."""
persisted = PersistedInventory.read(home, project_roots)
items = [
*_claude_items(
home=home,
mask_credential=mask_credential,
allow_secret="claude" in secret_backends,
project_roots=project_roots,
persisted=persisted,
),
*_codex_items(
home=home, mask_credential=mask_credential,
allow_secret="codex" in secret_backends,
project_roots=project_roots,
persisted=persisted,
),
*_opencode_items(
home=home, mask_credential=mask_credential, project_roots=project_roots,
persisted=persisted,
),
]
items.extend(_shell_items(persisted, mask_credential, items))
for backend, auth in (legacy_auth or {}).items():
if backend not in {"claude", "codex"}:
continue
secret = _oauth_text(auth, "api_key")
base_url = _oauth_text(auth, "base_url")
if not secret or any(
item.backend == backend and item.secret == secret and item.base_url == base_url
for item in items
):
continue
item_id, source_id = _ids(
backend, "api_key", "avibe-config", "import",
_stable_suffix(secret, base_url or ""),
)
masked = mask_credential(secret)
items.append(NativeMigrationItem(
id=item_id, source_id=source_id, backend=cast(Any, backend),
kind="api_key", masked_detail=masked, proposed_action="import",
selected=True, notes_key=_CUSTOM_ENDPOINT_NOTE if base_url else None,
vendor="anthropic" if backend == "claude" else "openai",
protocol="anthropic" if backend == "claude" else "openai_responses",
display_name="Anthropic" if backend == "claude" else "OpenAI",
secret=secret, base_url=base_url, masked_credential=masked,
))
if validate_base_url is not None:
valid_items: list[NativeMigrationItem] = []
for item in items:
try:
validate_base_url(item.base_url)
except Exception:
valid_items.append(replace(
item, proposed_action="reauth", selected=False, secret=None,
base_url=None, notes_key="settings.models.migration.blocked.config",
))
continue
valid_items.append(item)
items = valid_items
admitted: list[NativeMigrationItem] = []
for item in items:
if item.proposed_action == "import":
try:
_require_native_api_key_transport(item)
except MigrationConflictError:
item = _bearer_transport(item) or replace(
item, proposed_action="reauth", selected=False,
notes_key="settings.models.migration.blocked.transport",
)
admitted.append(item)
items = admitted
items = _deduplicate_opencode_items(items, validate_base_url)
existing_native_sources = {
source.vendor: source
for source in config.sources
if source.kind == "subscription" and source.supply_channel == "native_cli"
}
live_credentials = {source.id: source.credential_ref for source in config.sources}
candidates: list[NativeMigrationItem] = []
for item in items:
# Keep the credential/target identity independent of both consent's
# full file snapshots and an existing Source's custody placement.
# Completed receipts can then recognize the exact old grant without
# accepting old consent after a file changed.
item = replace(item, receipt_identity=item.id)
if (
item.native_store_placeholder
and (clean_native_stores or {}).get(item.backend) == item.native_store_revision
):
# A completed cleanup verified this exact metadata revision holds
# only unrelated native data (e.g. MCP OAuth). Do not read it again
# merely to rediscover the absence of subscription credentials.
continue
if item.native_store_placeholder and any(
copy.get("store_backend") == item.backend
and copy.get("store_routing", "") == (item.native_store_routing or "")
and copy.get("store_revision") == item.native_store_revision
and _retained_copy_live(copy, live_credentials)
for copy in (retained_native_ids or {}).values()
):
# An opaque store whose only credential is a kept, copied key. Its
# metadata revision was recorded at completion; any change re-offers.
continue
if (
item.kind != "oauth_native" and item.secret
and _retained_copy_live(
(retained_native_ids or {}).get(_retained_key_identity(item)), live_credentials,
)
):
# A completed takeover copied this exact static key and left it
# native by choice. It is shadowed by the Hub launch, not pending.
continue
native_source = existing_native_sources.get(item.vendor)
if item.kind == "oauth_native" and native_source is not None:
candidates.append(replace(
item,
source_id=native_source.id,
id=f"mig_{_stable_suffix(item.id, native_source.id)}",
))
continue
candidates.append(item)
return _bind_persisted_inventory(candidates, persisted)
def _validated_source(
item: NativeMigrationItem,
*,
now: datetime,
protocol: Literal["anthropic", "openai_responses", "openai_chat"],
validate_base_url: Callable[[object], Optional[str]],
credential_ref: str | None = None,
masked_credential: str | None = None,
discovered: tuple[DiscoveredModel, ...] = (),
catalog_efforts_by_model: Mapping[str, tuple[str, ...]],
) -> ModelHubSourceConfig:
keep_native = item.proposed_action == "keep_native"
controlled = item.proposed_action == "controlled_import"
imported_oauth = item.kind == "oauth_native" and item.proposed_action == "import"
discovered_at = now.isoformat()
models = []
if keep_native or imported_oauth:
model_ids = (
tuple(model.id for model in discovered)
if imported_oauth and discovered
else _native_model_ids(item.backend)
)
for model_id in model_ids:
resolution = resolve_reasoning_tiers(
protocol=protocol,
model_id=model_id,
catalog_efforts_by_model=catalog_efforts_by_model,
)
models.append(
{
"id": model_id,
"display_name": None,
"origin": "discovered",
"reasoning_efforts": list(resolution.efforts),
"reasoning_efforts_source": resolution.source,
"discovered_at": discovered_at,
}
)
else:
# Configured model entries remain manual; migration never invents an
# upstream inventory or a last-discovered timestamp for them.
for model in item.manual_models:
resolution = resolve_reasoning_tiers(
protocol=protocol,
model_id=model.id,
catalog_efforts_by_model=catalog_efforts_by_model,
)
models.append({
"id": model.id,
"display_name": model.display_name,
"origin": "manual",
"reasoning_efforts": list(resolution.efforts),
"reasoning_efforts_source": resolution.source,
"discovered_at": None,
})
payload: dict[str, object] = {
"id": item.source_id,
"created_at": discovered_at,
"last_discovered_at": discovered_at if models and (keep_native or imported_oauth) else None,
"kind": "subscription" if keep_native or controlled or imported_oauth else "api_key",
"vendor": item.vendor,
"display_name": item.display_name,
"protocol": protocol,
"base_url": validate_base_url(item.base_url),
"supply_channel": "native_cli" if keep_native else "hub",
"billing": "monthly" if keep_native or controlled or imported_oauth else "metered",
"state": {"status": "standby", "retry_at": None, "detail_key": None},
"usage": {
"cycle_used_pct": None,
"month_spend_cents": None,
"currency": None,
"projected_exhaust_at": None,
},
"models": models,
"credential_ref": credential_ref,
"account_label": item.account_label,
"masked_credential": masked_credential,
}
try:
return ModelHubSourceConfig.from_payload(payload)
except ValueError:
# Canonical Source validation is the last input boundary before custody.
# Invalid native metadata must not escape as an unredacted server error.
raise MigrationConflictError from None
def _native_auth_snapshot(host: MigrationHost, backends: tuple[str, ...]) -> dict:
reader = getattr(host.store, "native_auth_snapshot", None)
return reader(backends) if callable(reader) else {}
def _ensure_takeover_placement(
config: ModelHubConfig, source: ModelHubSourceConfig, backend: str,
) -> None:
"""Identity reuse still owes the consenting backend a configured placement."""
if not config.source_eligible_for_backend(source, backend):
raise MigrationConflictError
agent = config.agents[backend]
if source.id not in agent.sources.order and not any(
hop.source_id == source.id for route in agent.routes.values() for hop in route.hops
):
agent.sources.order.append(source.id)
async def _prepare_takeover(
host: MigrationHost,
previous: ModelHubConfig,
selected: list[NativeMigrationItem],
*,
mask_credential: Callable[[str], str],
validate_base_url: Callable[[object], Optional[str]],
consented: list[NativeMigrationItem] | None = None,
project_roots: tuple[Path, ...] = (),
retained_source_ids: tuple[str, ...] | None = None,
retained_item_ids: frozenset[str] = frozenset(),
clean_native_stores: Mapping[str, str] | None = None,
clean_api_keys: bool = False,
retained_keys: tuple[NativeMigrationItem, ...] = (),
) -> dict[str, Any]:
"""Stage all grants and durable before/after images, still native-owned.
``retained_keys`` are keys an earlier copy-only batch already copied; a
cleanup batch withdraws them natively without provisioning them again.
"""
for item in selected:
# Recheck local representability before cleanup, reuse or credential custody.
_require_native_api_key_transport(item)
clean_native_stores = dict(clean_native_stores or {})
cleanup_items = [
*selected,
*retained_keys,
*(item for item in (consented or []) if (
item.native_store_placeholder and item.backend in clean_native_stores
)),
]
edits = plan_native_cleanup(
cleanup_items, home=host.migration_home, project_roots=project_roots,
clean_api_keys=clean_api_keys,
)
updated = host._clone_config(previous)
provisioned: list[dict[str, str]] = []
source_ids: list[str] = list(retained_source_ids or ())
item_sources: dict[str, dict[str, str]] = {}
native_sources: dict[str, list[tuple[str, str]]] = {}
catalog = bundled_catalog_wire_efforts_by_model()
handoff_attempted = False
try:
# A completed receipt can authorize cleanup of the exact old material
# reintroduced by an external writer. Its current Hub refs are already
# authoritative; never provision that old OAuth snapshot again.
for item in selected:
# A static key reuses its existing Source below, which also
# records the copy's receipt; only a login is never re-provisioned.
if item.id in retained_item_ids and item.kind == "oauth_native":
continue
protocol = item.protocol
auth_options = {"auth_scheme": item.auth_scheme} if item.auth_scheme is not None else {}
reused = False
existing = next((source for source in updated.sources if source.id == item.source_id), None)
if item.kind != "oauth_native":
if not item.secret:
raise MigrationConflictError
# Old copy-only imports, including manually created sources,
# can retain their identity and routing without another key.
for candidate in updated.sources:
if (
candidate.kind == "api_key"
and candidate.vendor == item.vendor
and candidate.protocol == protocol
and candidate.base_url == validate_base_url(item.base_url)
and candidate.credential_ref
and await host._engine_call(host.adapter.matches_api_key_credential(
candidate.credential_ref, item.vendor, protocol,
item.secret, validate_base_url(item.base_url),
**auth_options,
))
):
# Matching custody is sufficient for identity reuse.
# Migration neither re-tests the key nor rewrites the
# existing Source's inventory, evidence or health.
reused = True
_ensure_takeover_placement(updated, candidate, item.backend)
native_sources.setdefault(item.backend, []).append((
item.native_provider_id or item.vendor, candidate.id,
))
source_ids.append(candidate.id)
item_sources[_retained_key_identity(item)] = {
"source_id": candidate.id, "credential_ref": candidate.credential_ref,
"key_fingerprint": _retained_key_fingerprint(item),
**({
"store_backend": item.backend, "store_routing": item.native_store_routing or "",
} if item.native_store_revision else {}),
}
break
if reused:
continue
if existing is not None and not (
existing.kind == "subscription"
and existing.supply_channel == "native_cli"
and item.kind == "oauth_native"
):
# A different key at the same native locator is a new Source,
# not permission to replace an already edited Hub source.
item = replace(item, source_id=f"src_{_stable_suffix(item.id, 'takeover')}")
existing = None
def reserved(ref: str) -> None:
# Use the final Source identity so recovery retains current
# Hub grants instead of misclassifying them as orphaned keys.
host.revocations.add(item.source_id, ref)
provisioned.append({
"source_id": item.source_id, "credential_ref": ref,
"kind": "oauth" if item.kind == "oauth_native" else "api_key",
})
if item.kind == "oauth_native":
if not item.oauth_material:
raise MigrationConflictError
credential_ref = await host._engine_call(host._provision_oauth_credential(
item.source_id, item.vendor, item.oauth_material,
on_reserved=reserved,
))
else:
credential_ref = await host._engine_call(host.adapter.provision_credential(
item.vendor, protocol, item.secret, validate_base_url(item.base_url),
on_reserved=reserved, **auth_options,
))
if not provisioned or provisioned[-1]["credential_ref"] != credential_ref:
raise MigrationConflictError
source = _validated_source(
item, now=host.now(), protocol=protocol,
validate_base_url=validate_base_url, credential_ref=credential_ref,
masked_credential=mask_credential(item.secret) if item.secret else None,
catalog_efforts_by_model=catalog,
)
if item.kind != "oauth_native":
# A migration is a local configuration transfer, not proof that
# the upstream accepts the saved key. Use the existing Saved
# marker until a real Gateway call verifies it.
host._mark_source_unverified(source)
if existing is not None:
# Custody changes, not the identity/menu/orders the user owns.
replacement = existing.to_payload()
replacement.update({
"supply_channel": "hub", "credential_ref": credential_ref,
"account_label": item.account_label or existing.account_label,
"state": source.state.to_payload(),
})
if not existing.models:
replacement["models"] = [model.to_payload() for model in source.models]
source = ModelHubSourceConfig.from_payload(replacement)
updated.sources = [source if value.id == source.id else value for value in updated.sources]
_ensure_takeover_placement(updated, source, item.backend)
# Now on the Hub, it is new to every backend its native CLI
# could not serve, OpenCode and Vibey among them: placed there
# like a new Source (a pending Vibey entry is seeded below
# instead). Where it already served, the order stays the user's.
host._apply_source_placement(updated, source, tuple(
backend for backend in MODEL_HUB_BACKENDS
if not updated.source_eligible_for_backend(existing, backend)
))
else:
updated.sources.append(source)
host._apply_source_placement(updated, source)
source_ids.append(source.id)
if item.kind != "oauth_native":
native_sources.setdefault(item.backend, []).append((
item.native_provider_id or item.vendor, source.id,
))
item_sources[_retained_key_identity(item)] = {
"source_id": source.id, "credential_ref": source.credential_ref,
"key_fingerprint": _retained_key_fingerprint(item),
**({
"store_backend": item.backend, "store_routing": item.native_store_routing or "",
} if item.native_store_revision else {}),
}
if updated.vibey_supply_pending:
# Once every Source of the batch is in place, reused identities too.
# Optional catalog enrichment must not add a network wait to migration.
await host._seed_vibey(updated, fetch_catalog=False)
backends = sorted({item.backend for item in [*(consented or selected), *retained_keys]})
native_before = _native_auth_snapshot(host, tuple(backends))
# Copy-only keeps the Avibe-saved native key; Hub launches shadow it.
# Cleanup clears the Avibe-saved key only when this batch carries it; an
# excluded key (e.g. an unimportable endpoint) keeps its Direct config.
carried = {
(item.backend, item.secret, item.base_url)
for item in [*selected, *retained_keys] if item.secret
}
credential_backends = {
backend for backend in {item.backend for item in [*selected, *retained_keys]}
if not native_before.get(backend, {}).get("api_key")
or (
backend, native_before[backend]["api_key"], native_before[backend].get("base_url"),
) in carried
} if clean_api_keys else set()
native_after = {
backend: ({
name: ("oauth" if name == "auth_mode" else True if name == "auth_mode_set" else None)
for name in values
} if backend in credential_backends else dict(values))
for backend, values in native_before.items()
}
updated.enabled = True
for backend in backends:
updated.agents[backend].mode = "hub"
# Source import owns this reconciliation, not the mode transition:
# a user may have switched to Hub before accepting migration.
host._carry_agent_selections(
updated, backend, native_sources=native_sources.get(backend, ()), fetch_catalog=False,
)
updated = ModelHubConfig.from_payload(updated.to_payload())
for edit in edits:
edit.check()
record = {
"version": 1, "phase": "prepared",
"items": [item.to_payload() for item in (consented or selected)],
"inventory_ids": [item.receipt_identity or item.id for item in (consented or selected)],
"backends": backends, "source_ids": source_ids,
"credentials": provisioned,
"previous": previous.to_payload(), "updated": updated.to_payload(),
"files": [edit.to_payload() for edit in edits],
"native_before": native_before, "native_after": native_after,
"keychain": [],
"clean_native_stores": clean_native_stores,
# Each copied key stays hidden only while its Hub Source exists.
"clean_api_keys": clean_api_keys,
"retained_native_ids": {} if clean_api_keys else {
identity: copy for identity, copy in item_sources.items()
},
# A cleanup batch withdraws these kept keys, retiring their receipts.
# Identities and material fingerprints both retire: a receipt
# written under an earlier route still names this withdrawn key.
"withdrawn_native_ids": sorted({
name for item in [*selected, *retained_keys]
if clean_api_keys and item.kind != "oauth_native"
for name in (_retained_key_identity(item), _retained_key_fingerprint(item))
}),
}
seen_stores: set[str] = set()
for item in native_store_items([*selected, *retained_keys], clean_api_keys=clean_api_keys):
edit = item.native_store_edit
if not edit or item.native_store_revision in seen_stores:
continue
operations = [operation for operation in edit["operations"] if operation["kind"] == "keychain"]
if operations:
record["keychain"].append({**edit, "operations": operations})
seen_stores.add(item.native_store_revision)
# Replacement can succeed before a durability/readback failure is
# reported. From this attempt onward recovery owns the refs: the
# prepared record if present, otherwise their write-ahead revocations.
# Never revoke a grant that a possibly durable prepared record needs.
handoff_attempted = True
host.migration_journal.save(record)
return record
finally:
if not handoff_attempted:
for credential in reversed(provisioned):
await host._rollback_credential(
credential["source_id"],
credential["credential_ref"],
)
async def _revert_takeover(host: MigrationHost, record: dict[str, Any]) -> None:
record["phase"] = "reverting"
host.migration_journal.save(record)
previous = ModelHubConfig.from_payload(record["previous"])
updated = ModelHubConfig.from_payload(record["updated"])
current = host.store.load()
if current.to_payload() not in (previous.to_payload(), updated.to_payload()):
raise MigrationConflictError
if current.to_payload() == updated.to_payload():
await host._save_config(previous)
host._engine_synced = False
for raw in reversed(record["files"]):
edit = NativeFileEdit.from_payload(raw)
# A compare-only guard never owned any bytes. An external edit must
# stop forward publication, but cannot prevent rollback of our writes.
if edit.before != edit.after:
edit.apply(reverse=True)
for edit in reversed(record.get("keychain", [])):
await asyncio.to_thread(apply_keychain_edit, edit, reverse=True)
for credential in reversed(record["credentials"]):
await host._rollback_credential(
credential["source_id"],
credential["credential_ref"],
)
host._reconcile_native_auth(tuple(record["backends"]))
host.migration_journal.forget()
host.migration_blocked_backends.difference_update(record["backends"])
async def _verify_clean_native_stores(host: MigrationHost, record: Mapping[str, Any]) -> None:
for backend, revision in record.get("clean_native_stores", {}).items():
snapshot = await asyncio.to_thread(
read_native_oauth, backend, home=host.migration_home,
)
if (
snapshot is None or snapshot.revision != revision
or (snapshot.payload or {}).get("status") != "metadata_only"
):
raise MigrationConflictError
async def _record_retained_store_revisions(host: MigrationHost, record: dict[str, Any]) -> None:
"""Bind each kept key held in an opaque store to that store's final revision."""
for copy in record.get("retained_native_ids", {}).values():
backend = copy.get("store_backend")
if backend is None:
continue
# The store still holds this key, so it is not verified clean: it stays
# hidden only while the copied Hub source is live.
record.get("clean_native_stores", {}).pop(backend, None)
snapshot = await asyncio.to_thread(read_native_oauth, backend, home=host.migration_home)
verified = record.get("verified_store_revisions", {}).get(backend)
# Bind only the revision verified against our post-edit image; a later
# external write stays unbound, so its store is offered again.
if (
snapshot is not None and (snapshot.payload or {}).get("status") == "metadata_only"
and (verified is None or snapshot.revision == verified)
):
copy["store_revision"] = snapshot.revision
async def _resume_takeover(
host: MigrationHost,
record: dict[str, Any],
verify_idle: Callable[[], Awaitable[None]] | None = None,
) -> tuple[int, list[dict]]:
if record["phase"] == "complete":
current = host.store.load()
if (
not set(record["source_ids"]).issubset(source.id for source in current.sources)
or any(current.agents[backend].mode != "hub" for backend in record["backends"])
or record.get("source_credentials") != {
source.id: source.credential_ref
for source in current.sources if source.id in record["source_ids"]
}
):
raise MigrationConflictError
if record.get("outcome") == "needs_auth":
raise MigrationCredentialsInvalidError
if record.get("outcome") == "reauth_requested":
raise MigrationConflictError
return len(record["items"]), [
position for source_id in record["source_ids"] for position in host._added_to(source_id)
]
host.migration_blocked_backends.update(record["backends"])
if verify_idle is None:
raise MigrationConflictError
if record["phase"] == "reverting":
await _revert_takeover(host, record)
raise MigrationConflictError
try:
await _verify_clean_native_stores(host, record)
if record["phase"] == "prepared":
# Installation and host compatibility are knowable before custody.
# Staged grants are outside CPA's watched directory, so ensuring
# the dependency here cannot publish them. An unavailable runtime
# must leave a working native login intact.
await host._ensure_runtime_dependency()
await verify_idle()
await _verify_clean_native_stores(host, record)
for edit in record.get("keychain", []):
await asyncio.to_thread(apply_keychain_edit, edit)
for raw in record["files"]:
NativeFileEdit.from_payload(raw).apply()
record["phase"] = "withdrawn"
host.migration_journal.save(record)
previous = ModelHubConfig.from_payload(record["previous"])
updated = ModelHubConfig.from_payload(record["updated"])
current = host.store.load()
terminal = record.get("terminal")
if current.to_payload() not in (
previous.to_payload(), updated.to_payload(),
terminal.get("config") if terminal else None,
):
raise MigrationConflictError
if record["phase"] == "withdrawn":
await _verify_clean_native_stores(host, record)
# Save the decision without projecting staged grants into CPA.
# sync_sources is a runtime write, not a config-only operation.
await host._save_config(updated)
if previous.vibey_supply_pending and not updated.vibey_supply_pending:
await host._announce_vibey_seed()
host._engine_synced = False
host._reconcile_native_auth(tuple(record["backends"]))
# This durable marker precedes any credential exposure to CPA.
# An empty-container-only confirmation transferred no grant and
# changed no native bytes: keep it reversible through runtime start
# so a newly observed login can be presented for fresh consent.
if (
record["source_ids"] or record["credentials"]
or any(raw["before"] != raw["after"] for raw in record["files"])
or record.get("keychain")
or record["native_before"] != record["native_after"]
):
record["phase"] = "exposed"
host.migration_journal.save(record)
else:
# Recovery may start with an equal persisted Hub config but stale
# launch consumers. Reconcile before any possible publication.
host._reconcile_native_auth(tuple(record["backends"]))
for raw in record["files"]:
NativeFileEdit.from_payload(raw).check(applied=True)
# Store mutations are replayable and must still match their cleaned
# state before a grant can be published to CPA.
if record.get("keychain"):
from vibe.native_oauth_store import check_keychain_edit
record.setdefault("clean_native_stores", {})
for edit in record["keychain"]:
snapshot = await asyncio.to_thread(
read_native_oauth, edit["backend"], home=host.migration_home,
)
# Bind the public metadata revision to the verified private
# post-state. A detected intervening login prevents completion.
await asyncio.to_thread(check_keychain_edit, edit, applied=True)
if snapshot is not None:
record.setdefault("verified_store_revisions", {})[edit["backend"]] = snapshot.revision
if snapshot and (snapshot.payload or {}).get("status") == "metadata_only":
record["clean_native_stores"][edit["backend"]] = snapshot.revision
await verify_idle()
if terminal:
# Every terminal path binds kept keys before its receipt.
await _record_retained_store_revisions(host, record)
return await _finish_rejected_takeover(host, record)
for credential in record["credentials"]:
if credential["kind"] == "oauth":
await host._engine_call(host.adapter.activate_oauth_credential(credential["credential_ref"]))
await host._ensure_runtime_dependency()
# Always reconcile, including recovery with equal before/after config.
# _commit_synced intentionally skips equal bindings and cannot do this.
await host._sync_sources(updated)
host._engine_synced = True
await host._engine_call(host.adapter.start())
invalid_source_ids = []
for credential in record["credentials"]:
if credential["kind"] == "oauth":
if credential["source_id"] in record.get("validated_source_ids", []):
continue
async def validate(ref: str) -> bool:
try:
await host.adapter.validate_oauth_credential(ref)
except OAuthCredentialRejectedError:
return False
return True
if not await host._engine_call(validate(credential["credential_ref"])):
invalid_source_ids.append(credential["source_id"])
else:
record.setdefault("validated_source_ids", []).append(credential["source_id"])
host.migration_journal.save(record)
await _verify_clean_native_stores(host, record)
# Runtime start is another await boundary. A new saved login or
# consumer introduced there must not disappear behind a receipt.
for raw in record["files"]:
NativeFileEdit.from_payload(raw).check(applied=True)
if invalid_source_ids:
terminal_config = host._clone_config(updated)
for source in terminal_config.sources:
if source.id in invalid_source_ids:
source.state = ModelHubSourceStateConfig(
status="needs_action",
detail_key="models.source.needs_action.oauth_expired",
)
# Persist the terminal decision before its config write. A crash
# between either write and the receipt must finish custody, never
# restore the original grant or repeat a rejected refresh.
await _record_retained_store_revisions(host, record)
record["terminal"] = {
"invalid_source_ids": invalid_source_ids,
"config": terminal_config.to_payload(),
}
host.migration_journal.save(record)
return await _finish_rejected_takeover(host, record)
host._reconcile_native_auth(tuple(record["backends"]))
await _record_retained_store_revisions(host, record)
host.migration_journal.complete(record)
host.migration_blocked_backends.difference_update(record["backends"])
return len(record["items"]), [
position for source_id in record["source_ids"] for position in host._added_to(source_id)
]
except BaseException:
if record["phase"] in {"prepared", "withdrawn"}:
await _revert_takeover(host, record)
raise
async def _finish_rejected_takeover(
host: MigrationHost, record: dict[str, Any],
) -> tuple[int, list[dict]]:
await host._save_config(ModelHubConfig.from_payload(record["terminal"]["config"]))
host._reconcile_native_auth(tuple(record["backends"]))
host.migration_journal.complete(record)
host.migration_blocked_backends.difference_update(record["backends"])
raise MigrationCredentialsInvalidError
async def apply_native_migration(
host: MigrationHost,
item_ids: object,
*,
mask_credential: Callable[[str], str],
validate_base_url: Callable[[object], Optional[str]],
clean_api_keys: bool = False,
) -> tuple[int, list[dict]]:
"""Own a takeover from consent through cleanup; callers shield cancellation.
Static API keys are copied and left native unless ``clean_api_keys``.
"""
if (
not isinstance(item_ids, list)
or not all(isinstance(value, str) and value for value in item_ids)
or len(set(item_ids)) != len(item_ids)
):
raise MigrationConflictError
if not item_ids:
return 0, []
async with host._migration_lock:
completed_record = None
record = host.migration_journal.load() or host.migration_journal.completed()
# A copy-only batch whose Sources were deleted or re-keyed no longer
# holds its still-native keys; the same rows then migrate afresh. A
# cleanup receipt keeps guarding the material it withdrew.
replayable = record is not None and (
record["phase"] != "complete" or record.get("clean_api_keys", True)
or _receipt_sources_intact(host, record)
)
if record is not None:
same_selection = {item["id"] for item in record["items"]} == set(item_ids)
if record["phase"] != "complete" and not same_selection:
raise MigrationConflictError
# Receipts predating the option always cleaned native keys. A
# pending journal from before it already staged that decision and
# resumes as staged. A completed batch is replayed only with its
# own choice; with another one the rows migrate afresh, which
# requires the native credentials to be present again.
option_changed = replayable and same_selection and (
"clean_api_keys" in record or record["phase"] == "complete"
) and record.get("clean_api_keys", True) != clean_api_keys
if option_changed and record["phase"] != "complete":
raise MigrationConflictError
if same_selection and replayable and not option_changed:
if record["phase"] == "complete":
async with host.migration_guard(tuple(record["backends"])) as verify_idle:
async with host._mutation_lock:
result = await _resume_takeover(host, record)
await verify_idle()
residual = await asyncio.to_thread(
scan_native_configs, host.store.load(),
mask_credential=mask_credential, home=host.migration_home,
validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, tuple(record["backends"])),
project_roots=host.migration_project_roots(),
clean_native_stores=record.get("clean_native_stores"),
retained_native_ids=record.get("retained_native_ids"),
)
if not any(
item.backend in record["backends"]
and (item.proposed_action == "import" or item.config_blocker)
for item in residual
):
return result
completed_record = record
else:
async with host.migration_guard(tuple(record["backends"])) as verify_idle:
async with host._mutation_lock:
return await _resume_takeover(host, record, verify_idle)
available = await asyncio.to_thread(
scan_native_configs, host.store.load(), mask_credential=mask_credential,
home=host.migration_home,
validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, tuple(sorted(NATIVE_CLI_BACKENDS))),
project_roots=host.migration_project_roots(),
clean_native_stores=(host.migration_journal.completed() or {}).get("clean_native_stores"),
retained_native_ids=(host.migration_journal.completed() or {}).get("retained_native_ids"),
)
selected = [item for item in available if item.id in item_ids]
if len(selected) != len(item_ids) or any(item.proposed_action != "import" for item in selected):
raise MigrationConflictError
backends = tuple(sorted({item.backend for item in selected}))
if any(set(item.required_backends) - set(backends) for item in selected):
raise MigrationConflictError
# A takeover moves every credential the Hub can carry, so selection is
# grouped by backend. Rows it cannot carry stay native: a Hub launch
# pins its own connection above them, so they are shadowed, not used.
if any(
item.backend in backends and item.proposed_action == "import" and item.id not in item_ids
for item in available
):
raise MigrationConflictError
# Hub mode over a native config the CLI cannot parse fails every launch.
if any(item.backend in backends and item.config_blocker for item in available):
raise MigrationConflictError
if clean_api_keys:
# Cleanup also withdraws keys a copy-only batch kept. Such a key
# may be shared with another backend (e.g. one shell variable);
# joint cleanup then spans that backend's kept keys as well.
hidden = [
item for item in await asyncio.to_thread(
scan_native_configs, host.store.load(), mask_credential=mask_credential,
home=host.migration_home, validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, tuple(sorted(NATIVE_CLI_BACKENDS))),
project_roots=host.migration_project_roots(),
clean_native_stores=(host.migration_journal.completed() or {}).get("clean_native_stores"),
)
if item.kind != "oauth_native" and item.proposed_action == "import"
and item.id not in {row.id for row in available}
]
scope = set(backends)
while True:
grown = scope | {
backend for item in hidden if item.backend in scope for backend in item.required_backends
}
if grown == scope:
break
scope = grown
if any(
item.backend in scope - set(backends) and item.proposed_action == "import"
for item in available
):
# A linked backend still has credentials awaiting consent.
raise MigrationConflictError
backends = tuple(sorted(scope))
retained_inventory_ids = (
set(record.get("inventory_ids", [item["id"] for item in record["items"]]))
& {item.receipt_identity or item.id for item in selected}
if replayable and record["phase"] == "complete" else set()
)
previous_oauth_backends = (
host.migration_journal.oauth_custody_backends(record)
if record is not None and record["phase"] == "complete" else frozenset()
)
if retained_inventory_ids:
# Fresh file-bound consent may describe the same old grant that
# an external writer restored after cleanup. Keep the current Hub
# credential rather than provisioning/refreshing that old grant.
# Before file-bound IDs existed, receipt item IDs already were
# these opaque inventory IDs; preserve that exact legacy proof.
# Consent can add or omit other backends. Grant ownership is not
# conditional on the entire selection being repeated.
completed_record = record
async with host.migration_guard(backends) as verify_idle:
async with host._mutation_lock:
if completed_record is not None:
# The guards above and below are separate acquisitions:
# recheck persisted ownership before a cleanup-only replay.
await _resume_takeover(host, completed_record)
previous = host.store.load()
project_roots = host.migration_project_roots()
rescanned = await asyncio.to_thread(
scan_native_configs, previous, mask_credential=mask_credential, home=host.migration_home,
validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, backends),
secret_backends=backends,
project_roots=project_roots,
clean_native_stores=(host.migration_journal.completed() or {}).get("clean_native_stores"),
retained_native_ids=(host.migration_journal.completed() or {}).get("retained_native_ids"),
)
consented = selected
selected = []
retained_item_ids: set[str] = set()
clean_native_stores: dict[str, str] = {}
for original in consented:
resolved = [
item for item in rescanned
if (
item.backend == original.backend
and item.native_store_revision == original.native_store_revision
and item.native_store_revision is not None
)
] if original.native_store_placeholder else [
item for item in rescanned if item.id == original.id
]
if original.native_store_placeholder and not resolved:
# A consent-time secret read can establish that an
# opaque container holds only unrelated data. Bind the
# absence to the same metadata, routing and Source
# identity before recording it as verified clean.
metadata_rows = await asyncio.to_thread(
scan_native_configs, previous,
mask_credential=mask_credential, home=host.migration_home,
validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, backends),
project_roots=project_roots,
)
if any(
item.id == original.id
and item.native_store_placeholder
and item.native_store_revision == original.native_store_revision
for item in metadata_rows
) and not any(
item.backend == original.backend and item.native_store_revision is not None
for item in rescanned
):
clean_native_stores[original.backend] = original.native_store_revision
continue
if original.native_store_placeholder and not any(
item.id == original.id for item in resolved
):
# Container revision alone does not bind the routing
# target or an existing native Source selected by UI.
raise MigrationConflictError
if not resolved or any(
item.proposed_action != "import" or item.native_store_placeholder
for item in resolved
):
raise MigrationConflictError
if (
original.backend in previous_oauth_backends
and (original.receipt_identity or original.id) not in retained_inventory_ids
and any(item.kind == "oauth_native" for item in resolved)
):
# Snapshot/revision changes cannot distinguish new
# authorization from an old refresh token copied into
# an edited container. Only Hub reauthentication can
# establish a fresh grant; never reprovision by guess.
raise MigrationReauthorizationRequiredError
selected.extend(item for item in resolved if item not in selected)
if (original.receipt_identity or original.id) in retained_inventory_ids:
retained_item_ids.update(item.id for item in resolved)
if any(
item.backend in backends and (
(item.proposed_action == "import" and item not in selected)
or item.config_blocker
)
for item in rescanned
):
raise MigrationConflictError
retained_keys: tuple[NativeMigrationItem, ...] = ()
if clean_api_keys:
# Keys a copy-only batch kept are hidden from consent while
# their Hub copy lives, yet cleanup must withdraw them too
# or they read as unselected native credentials.
shown = {item.id for item in rescanned}
unfiltered = await asyncio.to_thread(
scan_native_configs, previous, mask_credential=mask_credential,
home=host.migration_home, validate_base_url=validate_base_url,
legacy_auth=_native_auth_snapshot(host, backends),
secret_backends=backends, project_roots=project_roots,
clean_native_stores=(host.migration_journal.completed() or {}).get("clean_native_stores"),
)
retained_keys = tuple(
item for item in unfiltered
if item.backend in backends and item.id not in shown
and item.kind != "oauth_native" and item.proposed_action == "import" and item.secret
)
record = await _prepare_takeover(
host, previous, selected, mask_credential=mask_credential,
validate_base_url=validate_base_url,
consented=consented,
project_roots=project_roots,
retained_source_ids=(
tuple(completed_record["source_ids"])
if completed_record is not None else None
),
retained_item_ids=frozenset(retained_item_ids),
clean_native_stores=clean_native_stores,
clean_api_keys=clean_api_keys,
retained_keys=retained_keys,
)
return await _resume_takeover(host, record, verify_idle)
async def recover_native_migration(host: MigrationHost) -> None:
"""Recover confirmed work before CPA runtime recovery or native admission."""
record = host.migration_journal.load()
if record is None or record["phase"] == "complete":
return
host.migration_blocked_backends.update(record["backends"])
async with host._migration_lock:
async with host.migration_guard(tuple(record["backends"])) as verify_idle:
async with host._mutation_lock:
try:
await _resume_takeover(host, record, verify_idle)
except MigrationCredentialsInvalidError:
# The durable Source state is the repair entry point.
# No native credential or admission gate remains owned.
pass
async def prepare_takeover_reauthentication(host: MigrationHost, source_id: str) -> None:
"""Honor explicit Hub reauthentication without guessing refresh validity.
This is not a migration-success path. The user has acknowledged replacing
authentication in Hub; release only the completed native withdrawal, keep
every current engine grant, and let the existing Hub OAuth flow repair it.
"""
async with host._migration_lock:
record = host.migration_journal.load()
if record is None:
return
if record["phase"] != "exposed":
raise MigrationConflictError
oauth_ids = [
credential["source_id"] for credential in record["credentials"]
if credential["kind"] == "oauth"
]
if source_id not in oauth_ids:
raise MigrationConflictError
async with host.migration_guard(tuple(record["backends"])) as verify_idle:
async with host._mutation_lock:
if not record.get("terminal"):
updated = ModelHubConfig.from_payload(record["updated"])
if host.store.load().to_payload() != updated.to_payload():
raise MigrationConflictError
unresolved = [
value for value in oauth_ids
if value == source_id or value not in record.get("validated_source_ids", [])
]
terminal = host._clone_config(updated)
for source in terminal.sources:
if source.id in unresolved:
source.state = ModelHubSourceStateConfig(
status="needs_action",
detail_key="models.source.needs_action.oauth_expired",
)
record["terminal"] = {
"invalid_source_ids": unresolved,
"config": terminal.to_payload(),
"reason": "reauth_requested",
}
host.migration_journal.save(record)
try:
# Reuses strict file/store cleanup checks, persisted config
# identity, and idle verification before removing any gate.
await _resume_takeover(host, record, verify_idle)
except MigrationCredentialsInvalidError:
pass