@0dai-dev/cli 4.3.6 → 4.3.8

package/lib/python/provider_registry.py

@@ -0,0 +1,1211 @@
+#!/usr/bin/env python3
+"""Local BYOK/custom-provider registry and project binding helpers."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import pathlib
+import secrets
+import urllib.parse
+from typing import Any
+
+import project_manager as pm
+from json_utils import load_json as _load_json, save_json as _save_json
+
+
+AUTH_DIR = pathlib.Path.home() / ".0dai"
+DB_DIR = AUTH_DIR / "db"
+KEYS_PATH = DB_DIR / "provider_keys.json"
+SECRETS_DIR = AUTH_DIR / "provider-secrets"
+
+SUPPORTED_ENDPOINT_KINDS = {
+    "openai_compatible",
+    "anthropic_compatible",
+    "native_google",
+    "custom_adapter",
+}
+SUPPORTED_AUTH_MODES = {
+    "bearer",
+    "x-api-key",
+    "custom_header",
+}
+SUPPORTED_BACKEND_MODES = {
+    "",
+    "direct",
+    "indirect",
+}
+
+SUPPORT_MATRIX = {
+    "openai_compatible": {
+        "noninteractive": "direct",
+        "opencode": "direct",
+        "claude": "indirect",
+        "capi": "indirect",
+        "gemini": "indirect",
+        "qoder": "indirect",
+        "codex": "indirect",
+    },
+    "anthropic_compatible": {
+        "noninteractive": "direct",
+        "claude": "direct",
+        "capi": "indirect",
+        "opencode": "indirect",
+        "gemini": "indirect",
+        "qoder": "unsupported",
+        "codex": "unsupported",
+    },
+    "native_google": {
+        "noninteractive": "direct",
+        "gemini": "direct",
+        "claude": "indirect",
+        "capi": "indirect",
+        "opencode": "indirect",
+        "qoder": "unsupported",
+        "codex": "unsupported",
+    },
+    "custom_adapter": {
+        "noninteractive": "indirect",
+        "claude": "indirect",
+        "capi": "indirect",
+        "gemini": "indirect",
+        "opencode": "indirect",
+        "qoder": "unsupported",
+        "codex": "unsupported",
+    },
+}
+
+
+class ProviderRegistryError(RuntimeError):
+    """Raised for expected BYOK/provider registry validation errors."""
+
+
+def _now_iso() -> str:
+    import time
+
+    return time.strftime("%Y-%m-%dT%H:%M:%S+00:00", time.gmtime())
+
+
+def _normalize_owner_email(email: str) -> str:
+    normalized = str(email or "").strip().lower()
+    if not normalized or "@" not in normalized:
+        raise ProviderRegistryError("authenticated account email required")
+    return normalized
+
+
+def _normalize_label(label: str) -> str:
+    value = str(label or "").strip()
+    if not value:
+        raise ProviderRegistryError("label required")
+    return value[:80]
+
+
+def _normalize_provider_family(value: str) -> str:
+    normalized = "-".join(str(value or "").strip().lower().replace("_", "-").split())
+    if not normalized:
+        raise ProviderRegistryError("provider family required")
+    return normalized
+
+
+def _normalize_endpoint_kind(value: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if normalized not in SUPPORTED_ENDPOINT_KINDS:
+        raise ProviderRegistryError(
+            "endpoint_kind must be one of: " + ", ".join(sorted(SUPPORTED_ENDPOINT_KINDS))
+        )
+    return normalized
+
+
+def _normalize_auth_mode(value: str) -> str:
+    normalized = str(value or "bearer").strip().lower()
+    if normalized not in SUPPORTED_AUTH_MODES:
+        raise ProviderRegistryError(
+            "auth_mode must be one of: " + ", ".join(sorted(SUPPORTED_AUTH_MODES))
+        )
+    return normalized
+
+
+def _normalize_base_url(value: str) -> str:
+    raw = str(value or "").strip()
+    if not raw:
+        raise ProviderRegistryError("base_url required")
+    parsed = urllib.parse.urlparse(raw)
+    if parsed.scheme not in {"https", "http"} or not parsed.netloc:
+        raise ProviderRegistryError("base_url must be a valid http(s) URL")
+    if parsed.username or parsed.password:
+        raise ProviderRegistryError("base_url must not include embedded credentials")
+    if parsed.query or parsed.fragment:
+        raise ProviderRegistryError("base_url must not include query or fragment")
+    normalized = parsed._replace(path=parsed.path.rstrip("/"), params="", query="", fragment="").geturl()
+    return normalized
+
+
+def _normalize_agents(value: list[str] | tuple[str, ...] | str | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple)):
+        items = [str(item or "").strip().lower() for item in value]
+    else:
+        items = [part.strip().lower() for part in str(value or "").split(",")]
+    seen: list[str] = []
+    for item in items:
+        if item and item not in seen:
+            seen.append(item)
+    return seen
+
+
+def _normalize_backend_mode(value: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if normalized not in SUPPORTED_BACKEND_MODES:
+        raise ProviderRegistryError("preferred_backend_mode must be '', 'direct', or 'indirect'")
+    return normalized
+
+
+def _hash_secret(secret: str) -> str:
+    return hashlib.sha256(secret.encode("utf-8")).hexdigest()
+
+
+def _mask_secret(secret: str) -> str:
+    text = str(secret or "")
+    if len(text) <= 8:
+        return "***"
+    return f"{text[:4]}...{text[-4:]}"
+
+
+def _store_schema() -> dict[str, Any]:
+    return {"schema": 1, "updated_at": "", "keys": {}, "defaults": {}}
+
+
+def _normalize_defaults(defaults: Any, keys: dict[str, Any]) -> dict[str, dict[str, str]]:
+    if not isinstance(defaults, dict):
+        return {}
+    normalized: dict[str, dict[str, str]] = {}
+    for bucket, raw in defaults.items():
+        if isinstance(raw, dict):
+            owner = str(bucket or "").strip().lower()
+            if not owner:
+                continue
+            owner_map: dict[str, str] = {}
+            for provider_family, key_id in raw.items():
+                provider = str(provider_family or "").strip().lower()
+                ref = str(key_id or "").strip()
+                if provider and ref:
+                    owner_map[provider] = ref
+            if owner_map:
+                normalized[owner] = owner_map
+            continue
+        provider = str(bucket or "").strip().lower()
+        ref = str(raw or "").strip()
+        if not provider or not ref:
+            continue
+        record = keys.get(ref)
+        owner = str(record.get("owner_email") or "").strip().lower() if isinstance(record, dict) else ""
+        if not owner:
+            continue
+        normalized.setdefault(owner, {})[provider] = ref
+    return normalized
+
+
+def _load_store() -> dict[str, Any]:
+    data = _load_json(KEYS_PATH)
+    if not isinstance(data, dict):
+        return _store_schema()
+    keys = data.get("keys")
+    if not isinstance(keys, dict):
+        keys = {}
+    defaults = _normalize_defaults(data.get("defaults"), keys)
+    return {
+        "schema": 1,
+        "updated_at": str(data.get("updated_at") or ""),
+        "keys": keys,
+        "defaults": defaults,
+    }
+
+
+def _save_store(store: dict[str, Any]) -> None:
+    payload = {
+        "schema": 1,
+        "updated_at": _now_iso(),
+        "keys": store.get("keys", {}) if isinstance(store, dict) else {},
+        "defaults": store.get("defaults", {}) if isinstance(store, dict) else {},
+    }
+    _save_json(KEYS_PATH, payload)
+
+
+def _secret_path(key_id: str) -> pathlib.Path:
+    return SECRETS_DIR / f"{key_id}.secret"
+
+
+def _write_secret(key_id: str, secret: str) -> pathlib.Path:
+    if not secret:
+        raise ProviderRegistryError("api key required")
+    path = _secret_path(key_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(str(secret).strip() + "\n", encoding="utf-8")
+    try:
+        path.parent.chmod(0o700)
+    except OSError:
+        pass
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def load_secret(key_id: str) -> str:
+    path = _secret_path(str(key_id or "").strip())
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def _gen_key_id() -> str:
+    return f"llmkey_{secrets.token_hex(8)}"
+
+
+def _public_record(record: dict[str, Any], *, is_default: bool = False) -> dict[str, Any]:
+    return {
+        "key_id": str(record.get("key_id") or ""),
+        "owner_email": str(record.get("owner_email") or ""),
+        "label": str(record.get("label") or ""),
+        "provider_family": str(record.get("provider_family") or ""),
+        "endpoint_kind": str(record.get("endpoint_kind") or ""),
+        "base_url": str(record.get("base_url") or ""),
+        "auth_mode": str(record.get("auth_mode") or ""),
+        "default_model": str(record.get("default_model") or ""),
+        "status": str(record.get("status") or "active"),
+        "secret_hint": str(record.get("secret_hint") or ""),
+        "created_at": str(record.get("created_at") or ""),
+        "rotated_at": str(record.get("rotated_at") or ""),
+        "disabled_at": str(record.get("disabled_at") or ""),
+        "is_default": bool(is_default),
+    }
+
+
+def _default_key_id(store: dict[str, Any], owner_email: str, provider_family: str) -> str:
+    defaults = store.get("defaults", {}) if isinstance(store, dict) else {}
+    owner_defaults = defaults.get(owner_email, {}) if isinstance(defaults, dict) else {}
+    if not isinstance(owner_defaults, dict):
+        return ""
+    return str(owner_defaults.get(provider_family) or "").strip()
+
+
+def support_matrix(endpoint_kind: str) -> dict[str, str]:
+    normalized = _normalize_endpoint_kind(endpoint_kind)
+    return dict(SUPPORT_MATRIX[normalized])
+
+
+def format_support_matrix(*, as_json: bool = False) -> str:
+    """Render the full SUPPORT_MATRIX as an operator-visible table or JSON."""
+    if as_json:
+        return json.dumps(SUPPORT_MATRIX, indent=2, ensure_ascii=False)
+    clis = sorted({cli for m in SUPPORT_MATRIX.values() for cli in m})
+    kinds = sorted(SUPPORT_MATRIX)
+    header = f"  {'ENDPOINT KIND':<24}" + "".join(f" {c:<14}" for c in clis)
+    sep = "  " + "-" * (24 + 14 * len(clis))
+    rows = []
+    for kind in kinds:
+        cells = []
+        for cli in clis:
+            mode = SUPPORT_MATRIX[kind].get(cli, "—")
+            cells.append(f" {mode:<14}")
+        rows.append(f"  {kind:<24}" + "".join(cells))
+    return "\n".join([header, sep, *rows])
+
+
+def validate_agent_support(endpoint_kind: str, agents: list[str]) -> list[str]:
+    """Return list of agents that are 'unsupported' for the given endpoint kind."""
+    matrix = support_matrix(endpoint_kind)
+    return [a for a in agents if matrix.get(a) == "unsupported"]
+
+
+def register_provider_key(
+    *,
+    owner_email: str,
+    label: str,
+    provider_family: str,
+    endpoint_kind: str,
+    base_url: str,
+    secret: str,
+    default_model: str = "",
+    auth_mode: str = "bearer",
+    set_default: bool = False,
+) -> dict[str, Any]:
+    owner = _normalize_owner_email(owner_email)
+    provider = _normalize_provider_family(provider_family)
+    endpoint = _normalize_endpoint_kind(endpoint_kind)
+    base = _normalize_base_url(base_url)
+    auth = _normalize_auth_mode(auth_mode)
+    model = str(default_model or "").strip()
+    masked = _mask_secret(secret)
+    key_id = _gen_key_id()
+    path = _write_secret(key_id, secret)
+    record = {
+        "key_id": key_id,
+        "owner_email": owner,
+        "label": _normalize_label(label),
+        "provider_family": provider,
+        "endpoint_kind": endpoint,
+        "base_url": base,
+        "auth_mode": auth,
+        "default_model": model,
+        "status": "active",
+        "secret_hash": _hash_secret(secret),
+        "secret_hint": masked,
+        "secret_ref": str(path),
+        "created_at": _now_iso(),
+        "rotated_at": "",
+        "disabled_at": "",
+    }
+    store = _load_store()
+    store["keys"][key_id] = record
+    if set_default or not _default_key_id(store, owner, provider):
+        store.setdefault("defaults", {}).setdefault(owner, {})[provider] = key_id
+    _save_store(store)
+    return _public_record(record, is_default=_default_key_id(store, owner, provider) == key_id)
+
+
+def list_provider_keys(owner_email: str) -> list[dict[str, Any]]:
+    owner = _normalize_owner_email(owner_email)
+    store = _load_store()
+    items: list[dict[str, Any]] = []
+    defaults = store.get("defaults", {}) if isinstance(store, dict) else {}
+    for key_id, raw in store.get("keys", {}).items():
+        if not isinstance(raw, dict):
+            continue
+        if str(raw.get("owner_email") or "").strip().lower() != owner:
+            continue
+        provider = str(raw.get("provider_family") or "")
+        owner_defaults = defaults.get(owner, {}) if isinstance(defaults, dict) else {}
+        items.append(_public_record(raw, is_default=isinstance(owner_defaults, dict) and owner_defaults.get(provider) == key_id))
+    return sorted(items, key=lambda item: (item["provider_family"], item["label"], item["key_id"]))
+
+
+def get_provider_key(owner_email: str, key_id: str) -> dict[str, Any]:
+    owner = _normalize_owner_email(owner_email)
+    ref = str(key_id or "").strip()
+    store = _load_store()
+    record = store.get("keys", {}).get(ref)
+    if not isinstance(record, dict) or str(record.get("owner_email") or "").strip().lower() != owner:
+        raise ProviderRegistryError("provider key not found")
+    provider = str(record.get("provider_family") or "")
+    is_default = _default_key_id(store, owner, provider) == ref
+    return _public_record(record, is_default=is_default)
+
+
+def set_default_provider_key(owner_email: str, key_id: str) -> dict[str, Any]:
+    owner = _normalize_owner_email(owner_email)
+    ref = str(key_id or "").strip()
+    store = _load_store()
+    record = store.get("keys", {}).get(ref)
+    if not isinstance(record, dict) or str(record.get("owner_email") or "").strip().lower() != owner:
+        raise ProviderRegistryError("provider key not found")
+    if str(record.get("status") or "active") != "active":
+        raise ProviderRegistryError("only active keys can become default")
+    provider = str(record.get("provider_family") or "")
+    store.setdefault("defaults", {}).setdefault(owner, {})[provider] = ref
+    _save_store(store)
+    return _public_record(record, is_default=True)
+
+
+def disable_provider_key(owner_email: str, key_id: str) -> dict[str, Any]:
+    owner = _normalize_owner_email(owner_email)
+    ref = str(key_id or "").strip()
+    store = _load_store()
+    record = store.get("keys", {}).get(ref)
+    if not isinstance(record, dict) or str(record.get("owner_email") or "").strip().lower() != owner:
+        raise ProviderRegistryError("provider key not found")
+    if str(record.get("status") or "") != "disabled":
+        record["status"] = "disabled"
+        record["disabled_at"] = _now_iso()
+        provider = str(record.get("provider_family") or "")
+        owner_defaults = store.get("defaults", {}).get(owner, {})
+        if isinstance(owner_defaults, dict) and owner_defaults.get(provider) == ref:
+            owner_defaults.pop(provider, None)
+            if not owner_defaults:
+                store.get("defaults", {}).pop(owner, None)
+        _save_store(store)
+    return _public_record(record, is_default=False)
+
+
+def rotate_provider_key(owner_email: str, key_id: str, *, secret: str) -> dict[str, Any]:
+    owner = _normalize_owner_email(owner_email)
+    ref = str(key_id or "").strip()
+    store = _load_store()
+    record = store.get("keys", {}).get(ref)
+    if not isinstance(record, dict) or str(record.get("owner_email") or "").strip().lower() != owner:
+        raise ProviderRegistryError("provider key not found")
+    path = _write_secret(ref, secret)
+    record["secret_hash"] = _hash_secret(secret)
+    record["secret_hint"] = _mask_secret(secret)
+    record["secret_ref"] = str(path)
+    record["rotated_at"] = _now_iso()
+    if str(record.get("status") or "") != "active":
+        record["status"] = "active"
+        record["disabled_at"] = ""
+    _save_store(store)
+    provider = str(record.get("provider_family") or "")
+    is_default = _default_key_id(store, owner, provider) == ref
+    return _public_record(record, is_default=is_default)
+
+
+def project_bindings_path(target: pathlib.Path) -> pathlib.Path:
+    return target / ".0dai" / "provider-bindings.json"
+
+
+def _load_project_bindings(target: pathlib.Path) -> dict[str, Any]:
+    path = project_bindings_path(target)
+    data = _load_json(path)
+    if not isinstance(data, dict):
+        return {"schema": 1, "project_id": "", "bindings": {}, "updated_at": ""}
+    bindings = data.get("bindings")
+    if not isinstance(bindings, dict):
+        bindings = {}
+    return {
+        "schema": 1,
+        "project_id": str(data.get("project_id") or ""),
+        "bindings": bindings,
+        "updated_at": str(data.get("updated_at") or ""),
+    }
+
+
+def _save_project_bindings(target: pathlib.Path, store: dict[str, Any]) -> None:
+    payload = {
+        "schema": 1,
+        "project_id": str(store.get("project_id") or ""),
+        "updated_at": _now_iso(),
+        "bindings": store.get("bindings", {}) if isinstance(store, dict) else {},
+    }
+    _save_json(project_bindings_path(target), payload)
+
+
+def _project_identity(target: pathlib.Path) -> dict[str, Any]:
+    try:
+        return pm._identity(target.resolve())
+    except Exception:  # noqa: BLE001 — project identity lookup failed
+        return {"project_id": "", "project_name": target.resolve().name}
+
+
+def bind_project_provider(
+    target: pathlib.Path,
+    *,
+    owner_email: str,
+    provider_family: str,
+    key_id: str,
+    default_model: str = "",
+    preferred_backend_mode: str = "",
+    enabled_agents: list[str] | tuple[str, ...] | str | None = None,
+) -> dict[str, Any]:
+    project = target.resolve()
+    owner = _normalize_owner_email(owner_email)
+    provider = _normalize_provider_family(provider_family)
+    key = get_provider_key(owner, key_id)
+    if key["provider_family"] != provider:
+        raise ProviderRegistryError("provider_family must match the selected key")
+    store = _load_project_bindings(project)
+    identity = _project_identity(project)
+    store["project_id"] = str(identity.get("project_id") or store.get("project_id") or "")
+    binding = {
+        "provider_family": provider,
+        "provider_key_id": key["key_id"],
+        "default_model": str(default_model or key.get("default_model") or "").strip(),
+        "preferred_backend_mode": _normalize_backend_mode(preferred_backend_mode),
+        "enabled_agents": _normalize_agents(enabled_agents),
+        "updated_at": _now_iso(),
+    }
+    store.setdefault("bindings", {})[provider] = binding
+    _save_project_bindings(project, store)
+    return dict(binding, project_id=store["project_id"])
+
+
+def list_project_bindings(target: pathlib.Path) -> list[dict[str, Any]]:
+    project = target.resolve()
+    store = _load_project_bindings(project)
+    items: list[dict[str, Any]] = []
+    for provider, raw in store.get("bindings", {}).items():
+        if not isinstance(raw, dict):
+            continue
+        item = dict(raw)
+        item["provider_family"] = provider
+        item["project_id"] = store.get("project_id") or ""
+        items.append(item)
+    return sorted(items, key=lambda item: item["provider_family"])
+
+
+def resolve_provider_binding(
+    target: pathlib.Path,
+    *,
+    owner_email: str,
+    provider_family: str,
+) -> dict[str, Any]:
+    project = target.resolve()
+    owner = _normalize_owner_email(owner_email)
+    provider = _normalize_provider_family(provider_family)
+    store = _load_store()
+    bindings = _load_project_bindings(project)
+    binding = bindings.get("bindings", {}).get(provider)
+    source = ""
+    key_id = ""
+    if isinstance(binding, dict):
+        key_id = str(binding.get("provider_key_id") or "").strip()
+        source = "project_override"
+    if not key_id:
+        default_key = _default_key_id(store, owner, provider)
+        if default_key:
+            key_id = default_key
+            source = "account_default"
+    if not key_id:
+        raise ProviderRegistryError(f"no active provider binding for '{provider}'")
+    key = get_provider_key(owner, key_id)
+    if key["status"] != "active":
+        raise ProviderRegistryError(f"provider key '{key_id}' is not active")
+    support = support_matrix(key["endpoint_kind"])
+    effective_model = ""
+    preferred_backend_mode = ""
+    enabled_agents: list[str] = []
+    if isinstance(binding, dict):
+        effective_model = str(binding.get("default_model") or "").strip()
+        preferred_backend_mode = str(binding.get("preferred_backend_mode") or "").strip()
+        enabled_agents = _normalize_agents(binding.get("enabled_agents"))
+    if not effective_model:
+        effective_model = key["default_model"]
+    unsupported = validate_agent_support(key["endpoint_kind"], enabled_agents)
+    if unsupported:
+        raise ProviderRegistryError(
+            f"endpoint kind '{key['endpoint_kind']}' does not support direct execution "
+            f"via: {', '.join(unsupported)}. Use an indirect adapter or remove these agents "
+            f"from the binding."
+        )
+    return {
+        "project_id": str(bindings.get("project_id") or _project_identity(project).get("project_id") or ""),
+        "target": str(project),
+        "provider_family": provider,
+        "resolution_source": source,
+        "binding": dict(binding) if isinstance(binding, dict) else {},
+        "key": key,
+        "support_matrix": support,
+        "effective_model": effective_model,
+        "preferred_backend_mode": preferred_backend_mode,
+        "enabled_agents": enabled_agents,
+    }
+
+
+def render_snippet(
+    resolved: dict[str, Any],
+    *,
+    cli_name: str,
+    include_secret: bool = False,
+) -> dict[str, Any]:
+    key = dict(resolved.get("key") or {})
+    endpoint_kind = str(key.get("endpoint_kind") or "")
+    base_url = str(key.get("base_url") or "")
+    label = str(key.get("label") or key.get("provider_family") or "Custom Provider")
+    provider_family = str(key.get("provider_family") or "")
+    model = str(resolved.get("effective_model") or key.get("default_model") or "").strip()
+    secret_value = load_secret(str(key.get("key_id") or ""))
+    secret = secret_value if include_secret else "<stored secret>"
+    cli = str(cli_name or "").strip().lower()
+    support = dict(resolved.get("support_matrix") or {})
+    mode = support.get(cli, "unsupported")
+
+    if cli == "opencode":
+        if mode != "direct" or endpoint_kind != "openai_compatible":
+            raise ProviderRegistryError("OpenCode direct snippet is supported only for openai_compatible endpoints")
+        payload = {
+            "$schema": "https://opencode.ai/config.json",
+            "model": model,
+            "provider": {
+                label: {
+                    "npm": "@ai-sdk/openai-compatible",
+                    "name": label,
+                    "options": {
+                        "baseURL": base_url,
+                        "apiKey": secret,
+                    },
+                }
+            },
+        }
+        return {
+            "cli": cli,
+            "format": "json",
+            "direct_mode": mode,
+            "snippet": json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        }
+
+    if cli in {"claude", "capi"}:
+        if mode != "direct" or endpoint_kind != "anthropic_compatible":
+            raise ProviderRegistryError("Claude direct snippet is supported only for anthropic_compatible endpoints")
+        lines = [
+            f'export ANTHROPIC_BASE_URL="{base_url}"',
+            f'export ANTHROPIC_API_KEY="{secret}"',
+        ]
+        if model:
+            lines.append(f'export ANTHROPIC_MODEL="{model}"')
+            lines.append(f'export ANTHROPIC_SMALL_FAST_MODEL="{model}"')
+        lines.append('export DISABLE_NON_ESSENTIAL_MODEL_CALLS="1"')
+        lines.append('export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"')
+        return {
+            "cli": cli,
+            "format": "shell",
+            "direct_mode": mode,
+            "snippet": "\n".join(lines) + "\n",
+        }
+
+    if cli == "noninteractive":
+        if mode not in {"direct", "indirect"}:
+            raise ProviderRegistryError("noninteractive snippet is unsupported for this endpoint kind")
+        lines = [
+            f'export ODAI_CUSTOM_PROVIDER_FAMILY="{provider_family}"',
+            f'export ODAI_CUSTOM_ENDPOINT_KIND="{endpoint_kind}"',
+            f'export ODAI_CUSTOM_BASE_URL="{base_url}"',
+            f'export ODAI_CUSTOM_API_KEY="{secret}"',
+        ]
+        if model:
+            lines.append(f'export ODAI_CUSTOM_MODEL="{model}"')
+        return {
+            "cli": cli,
+            "format": "shell",
+            "direct_mode": mode,
+            "snippet": "\n".join(lines) + "\n",
+        }
+
+    raise ProviderRegistryError(f"snippet generation is not implemented for cli '{cli}'")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Per-Repo Provider Profiles (M19 — Team-tier $49/seat differentiator)
+# ──────────────────────────────────────────────────────────────────────────────
+
+GLOBAL_PROVIDERS_PATH = AUTH_DIR / "providers" / "global.json"
+AUDIT_LOG_PATH = AUTH_DIR / "audit" / "provider-changes.jsonl"
+
+# Built-in provider families (extensible)
+KNOWN_PROVIDERS = {
+    "anthropic": {
+        "endpoint_kind": "anthropic_compatible",
+        "env_prefix": "ANTHROPIC",
+        "base_url_env": "ANTHROPIC_BASE_URL",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "default_base_url": "https://api.anthropic.com",
+    },
+    "openai": {
+        "endpoint_kind": "openai_compatible",
+        "env_prefix": "OPENAI",
+        "base_url_env": "OPENAI_BASE_URL",
+        "api_key_env": "OPENAI_API_KEY",
+        "default_base_url": "https://api.openai.com/v1",
+    },
+    "openrouter": {
+        "endpoint_kind": "openai_compatible",
+        "env_prefix": "OPENROUTER",
+        "base_url_env": "OPENROUTER_BASE_URL",
+        "api_key_env": "OPENROUTER_API_KEY",
+        "default_base_url": "https://openrouter.ai/api/v1",
+    },
+    "ruapi": {
+        "endpoint_kind": "openai_compatible",
+        "env_prefix": "RUAPI",
+        "base_url_env": "RUAPI_BASE_URL",
+        "api_key_env": "RUAPI_API_KEY",
+        "default_base_url": "https://api.stepanovikov.uno/v1",
+    },
+    "deepseek": {
+        "endpoint_kind": "openai_compatible",
+        "env_prefix": "DEEPSEEK",
+        "base_url_env": "DEEPSEEK_BASE_URL",
+        "api_key_env": "DEEPSEEK_API_KEY",
+        "default_base_url": "https://api.deepseek.com/v1",
+    },
+    "ollama": {
+        "endpoint_kind": "openai_compatible",
+        "env_prefix": "OLLAMA",
+        "base_url_env": "OLLAMA_BASE_URL",
+        "api_key_env": "OLLAMA_API_KEY",
+        "default_base_url": "http://localhost:11434/v1",
+    },
+    "google": {
+        "endpoint_kind": "native_google",
+        "env_prefix": "GOOGLE",
+        "base_url_env": "GOOGLE_BASE_URL",
+        "api_key_env": "GOOGLE_API_KEY",
+        "default_base_url": "https://generativelanguage.googleapis.com",
+    },
+}
+
+
+def _repo_id(target: pathlib.Path) -> str:
+    """Generate stable repo ID from target path (for profile storage)."""
+    resolved = target.resolve()
+    # Try git remote first for stable cross-machine identity
+    try:
+        import subprocess
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=str(resolved),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            remote = result.stdout.strip()
+            # Normalize: strip .git suffix, take repo slug
+            import re
+            match = re.search(r"[/:]([^/]+/[^/]+?)(?:\.git)?$", remote)
+            if match:
+                return match.group(1).replace("/", "_").replace(":", "_")
+    except Exception:  # noqa: BLE001 — git remote get-url failed
+        pass
+    # Fallback: hash of resolved path
+    return hashlib.sha256(str(resolved).encode()).hexdigest()[:16]
+
+
+def _per_repo_profile_path(target: pathlib.Path) -> pathlib.Path:
+    """Return path to per-repo provider profile: ai/providers/<repo-id>/profile.json"""
+    repo_id = _repo_id(target)
+    return target.resolve() / "ai" / "providers" / repo_id / "profile.json"
+
+
+def _load_global_providers() -> dict[str, Any]:
+    """Load global provider defaults from ~/.0dai/providers/global.json"""
+    try:
+        return _load_json(GLOBAL_PROVIDERS_PATH) or {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_global_providers(data: dict[str, Any]) -> None:
+    """Save global provider defaults to ~/.0dai/providers/global.json"""
+    GLOBAL_PROVIDERS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _save_json(GLOBAL_PROVIDERS_PATH, data)
+
+
+def _load_repo_profile(target: pathlib.Path) -> dict[str, Any]:
+    """Load per-repo provider profile from ai/providers/<repo-id>/profile.json"""
+    path = _per_repo_profile_path(target)
+    try:
+        return _load_json(path) or {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_repo_profile(target: pathlib.Path, data: dict[str, Any]) -> pathlib.Path:
+    """Save per-repo provider profile to ai/providers/<repo-id>/profile.json"""
+    path = _per_repo_profile_path(target)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _save_json(path, data)
+    return path
+
+
+def _get_operator_id() -> str:
+    """Get operator ID from env or git config."""
+    # Try env first
+    op_id = os.environ.get("ODAI_OPERATOR_ID") or os.environ.get("USER") or os.environ.get("USERNAME")
+    if op_id:
+        return op_id
+    # Try git config
+    try:
+        import subprocess
+        result = subprocess.run(
+            ["git", "config", "user.email"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except Exception:  # noqa: BLE001 — git config user.email failed
+        pass
+    return "unknown"
+
+
+def write_audit_event(
+    event_type: str,
+    target: pathlib.Path | str,
+    old: dict[str, Any] | None,
+    new: dict[str, Any] | None,
+    operator_id: str = "",
+) -> pathlib.Path:
+    """Append audit event to ~/.0dai/audit/provider-changes.jsonl
+
+    Args:
+        event_type: Type of event (e.g., "switch", "set_default", "clear")
+        target: Target path (repo root)
+        old: Previous state (or None)
+        new: New state (or None)
+        operator_id: Operator identifier (auto-detected if empty)
+
+    Returns:
+        Path to audit log file
+    """
+    import fcntl
+
+    if not operator_id:
+        operator_id = _get_operator_id()
+
+    entry = {
+        "timestamp": _now_iso(),
+        "event_type": event_type,
+        "target_path": str(pathlib.Path(target).resolve()) if target else "",
+        "old": old,
+        "new": new,
+        "operator_id": operator_id,
+    }
+
+    AUDIT_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Thread/process-safe append with fcntl
+    with open(AUDIT_LOG_PATH, "a", encoding="utf-8") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+    return AUDIT_LOG_PATH
+
+
+def resolve_for_repo(target: pathlib.Path) -> dict[str, Any]:
+    """Resolve provider configuration for a repo, merging global + per-repo.
+
+    Resolution order:
+    1. Per-repo profile (ai/providers/<repo-id>/profile.json) — highest priority
+    2. Global defaults (~/.0dai/providers/global.json)
+
+    Returns:
+        {
+            "provider_name": str,       # e.g., "anthropic", "ruapi", "openai"
+            "base_url": str,            # API base URL
+            "api_key_ref": str,         # Env var name or secret ref
+            "api_key_value": str,       # Actual key value (from env or stored)
+            "endpoint_kind": str,       # e.g., "anthropic_compatible"
+            "source": str,              # "repo_profile" | "global_default" | "env_fallback"
+            "audit_trail": dict,        # Resolution metadata
+        }
+
+    Raises:
+        ProviderRegistryError: If no valid provider config found and no env fallback
+    """
+    resolved = target.resolve()
+    repo_id = _repo_id(resolved)
+
+    audit_trail = {
+        "repo_id": repo_id,
+        "target": str(resolved),
+        "resolved_at": _now_iso(),
+        "checked_sources": [],
+    }
+
+    # 1. Check per-repo profile
+    repo_profile = _load_repo_profile(resolved)
+    audit_trail["checked_sources"].append("repo_profile")
+
+    if repo_profile.get("provider_name"):
+        provider_name = repo_profile["provider_name"]
+        provider_info = KNOWN_PROVIDERS.get(provider_name, {})
+
+        base_url = repo_profile.get("base_url") or provider_info.get("default_base_url", "")
+        api_key_ref = repo_profile.get("api_key_ref") or provider_info.get("api_key_env", "")
+
+        # Resolve API key value
+        api_key_value = ""
+        if api_key_ref.startswith("llmkey_"):
+            # Stored secret reference
+            api_key_value = load_secret(api_key_ref)
+        else:
+            # Environment variable
+            api_key_value = os.environ.get(api_key_ref, "")
+
+        if not api_key_value:
+            # Try standard env var for this provider
+            env_var = provider_info.get("api_key_env", "")
+            if env_var:
+                api_key_value = os.environ.get(env_var, "")
+                if api_key_value:
+                    api_key_ref = env_var
+
+        if not api_key_value:
+            raise ProviderRegistryError(
+                f"Provider '{provider_name}' configured for {resolved.name} but no API key found. "
+                f"Set {api_key_ref} or export {provider_info.get('api_key_env', 'API_KEY')}=..."
+            )
+
+        audit_trail["resolution_source"] = "repo_profile"
+        return {
+            "provider_name": provider_name,
+            "base_url": base_url,
+            "api_key_ref": api_key_ref,
+            "api_key_value": api_key_value,
+            "endpoint_kind": provider_info.get("endpoint_kind", "openai_compatible"),
+            "model": repo_profile.get("model", ""),
+            "source": "repo_profile",
+            "audit_trail": audit_trail,
+        }
+
+    # 2. Check global defaults
+    global_config = _load_global_providers()
+    audit_trail["checked_sources"].append("global_default")
+
+    if global_config.get("default_provider"):
+        provider_name = global_config["default_provider"]
+        provider_info = KNOWN_PROVIDERS.get(provider_name, {})
+
+        base_url = global_config.get("base_url") or provider_info.get("default_base_url", "")
+        api_key_ref = global_config.get("api_key_ref") or provider_info.get("api_key_env", "")
+
+        api_key_value = ""
+        if api_key_ref.startswith("llmkey_"):
+            api_key_value = load_secret(api_key_ref)
+        else:
+            api_key_value = os.environ.get(api_key_ref, "")
+
+        if not api_key_value:
+            env_var = provider_info.get("api_key_env", "")
+            if env_var:
+                api_key_value = os.environ.get(env_var, "")
+                if api_key_value:
+                    api_key_ref = env_var
+
+        if not api_key_value:
+            raise ProviderRegistryError(
+                f"Global provider '{provider_name}' configured but no API key found. "
+                f"Export {provider_info.get('api_key_env', 'API_KEY')}=..."
+            )
+
+        audit_trail["resolution_source"] = "global_default"
+        return {
+            "provider_name": provider_name,
+            "base_url": base_url,
+            "api_key_ref": api_key_ref,
+            "api_key_value": api_key_value,
+            "endpoint_kind": provider_info.get("endpoint_kind", "openai_compatible"),
+            "model": global_config.get("model", ""),
+            "source": "global_default",
+            "audit_trail": audit_trail,
+        }
+
+    # 3. Environment fallback: detect from well-known env vars
+    audit_trail["checked_sources"].append("env_fallback")
+
+    for provider_name, provider_info in KNOWN_PROVIDERS.items():
+        env_var = provider_info.get("api_key_env", "")
+        if env_var and os.environ.get(env_var):
+            audit_trail["resolution_source"] = "env_fallback"
+            audit_trail["detected_provider"] = provider_name
+            return {
+                "provider_name": provider_name,
+                "base_url": os.environ.get(provider_info.get("base_url_env", ""), provider_info.get("default_base_url", "")),
+                "api_key_ref": env_var,
+                "api_key_value": os.environ.get(env_var, ""),
+                "endpoint_kind": provider_info.get("endpoint_kind", "openai_compatible"),
+                "model": "",
+                "source": "env_fallback",
+                "audit_trail": audit_trail,
+            }
+
+    # No provider found
+    raise ProviderRegistryError(
+        f"No provider configured for {resolved.name}. "
+        f"Use '0dai provider switch --target . --provider NAME' or export ANTHROPIC_API_KEY/OPENAI_API_KEY."
+    )
+
+
+def switch_provider(
+    target: pathlib.Path,
+    provider_name: str,
+    *,
+    base_url: str = "",
+    api_key_ref: str = "",
+    model: str = "",
+) -> dict[str, Any]:
+    """Switch a repo to a specific provider.
+
+    Args:
+        target: Repo root path
+        provider_name: Provider name (anthropic, openai, ruapi, etc.)
+        base_url: Optional custom base URL (uses provider default if empty)
+        api_key_ref: Optional API key ref (env var or llmkey_xxx)
+        model: Optional default model
+
+    Returns:
+        New profile dict
+
+    Raises:
+        ProviderRegistryError: If provider unknown or credentials missing
+    """
+    normalized = provider_name.lower().strip()
+    if normalized not in KNOWN_PROVIDERS:
+        raise ProviderRegistryError(
+            f"Unknown provider '{provider_name}'. "
+            f"Supported: {', '.join(sorted(KNOWN_PROVIDERS.keys()))}"
+        )
+
+    provider_info = KNOWN_PROVIDERS[normalized]
+
+    # Determine base URL
+    if not base_url:
+        base_url = provider_info.get("default_base_url", "")
+
+    # Determine API key reference
+    if not api_key_ref:
+        api_key_ref = provider_info.get("api_key_env", "")
+
+    # Verify credentials exist
+    api_key_value = ""
+    if api_key_ref.startswith("llmkey_"):
+        api_key_value = load_secret(api_key_ref)
+    else:
+        api_key_value = os.environ.get(api_key_ref, "")
+
+    if not api_key_value:
+        # Try standard env var
+        env_var = provider_info.get("api_key_env", "")
+        if env_var:
+            api_key_value = os.environ.get(env_var, "")
+            if api_key_value:
+                api_key_ref = env_var
+
+    if not api_key_value:
+        raise ProviderRegistryError(
+            f"Cannot switch to '{normalized}': no API key found. "
+            f"Export {provider_info.get('api_key_env', 'API_KEY')}=... first."
+        )
+
+    resolved = target.resolve()
+    old_profile = _load_repo_profile(resolved)
+
+    new_profile = {
+        "schema": 1,
+        "provider_name": normalized,
+        "base_url": base_url,
+        "api_key_ref": api_key_ref,
+        "model": model,
+        "updated_at": _now_iso(),
+    }
+
+    _save_repo_profile(resolved, new_profile)
+
+    # Audit log
+    write_audit_event(
+        event_type="switch",
+        target=resolved,
+        old=old_profile if old_profile else None,
+        new=new_profile,
+    )
+
+    return new_profile
+
+
+def list_providers_for_repo(target: pathlib.Path) -> list[dict[str, Any]]:
+    """List all providers and their status for a repo.
+
+    Returns list of provider dicts with 'source' indicator.
+    """
+    resolved = target.resolve()
+    repo_profile = _load_repo_profile(resolved)
+    global_config = _load_global_providers()
+
+    result = []
+    active_provider = repo_profile.get("provider_name") or global_config.get("default_provider") or ""
+
+    for name, info in sorted(KNOWN_PROVIDERS.items()):
+        env_var = info.get("api_key_env", "")
+        has_key = bool(os.environ.get(env_var)) if env_var else False
+
+        # Determine source
+        source = ""
+        if repo_profile.get("provider_name") == name:
+            source = "repo"
+        elif global_config.get("default_provider") == name:
+            source = "global"
+        elif has_key:
+            source = "env"
+
+        result.append({
+            "name": name,
+            "endpoint_kind": info.get("endpoint_kind", ""),
+            "base_url": repo_profile.get("base_url") if source == "repo" else info.get("default_base_url", ""),
+            "has_credentials": has_key or bool(load_secret(repo_profile.get("api_key_ref", ""))),
+            "source": source,
+            "active": name == active_provider,
+        })
+
+    return result
+
+
+def build_provider_env(provider_config: dict[str, Any]) -> dict[str, str]:
+    """Build environment variables for agent subprocess from provider config.
+
+    Args:
+        provider_config: Output from resolve_for_repo()
+
+    Returns:
+        Dict of env vars to inject into agent subprocess
+    """
+    provider_name = provider_config.get("provider_name", "")
+    provider_info = KNOWN_PROVIDERS.get(provider_name, {})
+
+    env = {}
+
+    base_url = provider_config.get("base_url", "")
+    api_key = provider_config.get("api_key_value", "")
+    endpoint_kind = provider_config.get("endpoint_kind", "")
+
+    if endpoint_kind == "anthropic_compatible":
+        if base_url:
+            env["ANTHROPIC_BASE_URL"] = base_url
+        if api_key:
+            env["ANTHROPIC_API_KEY"] = api_key
+    elif endpoint_kind == "openai_compatible":
+        if base_url:
+            env["OPENAI_BASE_URL"] = base_url
+        if api_key:
+            env["OPENAI_API_KEY"] = api_key
+        # Also set provider-specific vars
+        env_prefix = provider_info.get("env_prefix", "")
+        if env_prefix and env_prefix not in ("OPENAI", "ANTHROPIC"):
+            base_url_env = provider_info.get("base_url_env", "")
+            api_key_env = provider_info.get("api_key_env", "")
+            if base_url_env and base_url:
+                env[base_url_env] = base_url
+            if api_key_env and api_key:
+                env[api_key_env] = api_key
+    elif endpoint_kind == "native_google":
+        if base_url:
+            env["GOOGLE_BASE_URL"] = base_url
+        if api_key:
+            env["GOOGLE_API_KEY"] = api_key
+
+    # Generic ODAI vars for custom adapters
+    env["ODAI_PROVIDER_NAME"] = provider_name
+    env["ODAI_PROVIDER_SOURCE"] = provider_config.get("source", "")
+
+    return env
+
+
+def clear_repo_profile(target: pathlib.Path) -> bool:
+    """Clear per-repo provider profile, falling back to global default.
+
+    Returns True if profile was cleared, False if no profile existed.
+    """
+    resolved = target.resolve()
+    old_profile = _load_repo_profile(resolved)
+
+    if not old_profile:
+        return False
+
+    path = _per_repo_profile_path(resolved)
+    if path.is_file():
+        path.unlink()
+
+    write_audit_event(
+        event_type="clear",
+        target=resolved,
+        old=old_profile,
+        new=None,
+    )
+
+    return True