@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/provider_profiles.py

@@ -0,0 +1,1618 @@
+#!/usr/bin/env python3
+"""Local-first provider profiles for external model subscriptions and API keys.
+
+`native_subscription` is the Claude OAuth lane; API-key and custom-endpoint
+profiles back the RuAPI/opencode and other provider-backed lanes.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import ipaddress
+import json
+import os
+import pathlib
+import re
+import shutil
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+ROOT = pathlib.Path.home() / ".0dai" / "providers"
+PROFILES_PATH = ROOT / "profiles.json"
+BINDINGS_PATH = ROOT / "bindings.json"
+RUNTIME_ROOT = ROOT / "runtime"
+SECRETS_ROOT = pathlib.Path.home() / ".config" / "secrets" / "providers"
+LAUNCHER_ROOT = pathlib.Path.home() / ".local" / "bin"
+SCRIPT_PATH = pathlib.Path(__file__).resolve()
+SCHEMA_URL = "https://opencode.ai/config.json"
+
+PROVIDER_KINDS = {
+    "anthropic_compatible",
+    "google_ai",
+    "openai_compatible",
+}
+AUTH_MODES = {
+    "native_subscription",
+    "api_key",
+    "api_key_custom_endpoint",
+}
+SUPPORTED_AGENTS = {"claude", "capi", "gemini", "opencode"}
+WRAPPED_AGENTS = {"claude", "capi", "gemini", "opencode"}
+CAPI_AGENT = "capi"
+CAPI_AGENT_ALIASES = {"capi", "claude-api", "claude_api_custom", "claude-api-custom"}
+REQUEST_TIMEOUT_SECONDS = 45
+DEFAULT_TEST_PROMPT = "Reply with exactly OK"
+DEFAULT_HEADERS = {
+    "User-Agent": "0dai-provider-profiles/1",
+}
+GOOGLE_API_CLIENT = "0dai-provider-profiles/1"
+GEMINI_DEFAULT_APPROVAL_MODE = "auto_edit"
+
+PROVIDER_SPECS: dict[str, dict[str, Any]] = {
+    "anthropic_compatible": {
+        "secret_env_key": "ANTHROPIC_API_KEY",
+        "default_base_url": "https://api.anthropic.com",
+        "default_model": "claude-sonnet-4-20250514",
+        "opencode_package": "@ai-sdk/anthropic",
+        "default_cli_targets": ["capi", "opencode"],
+    },
+    "google_ai": {
+        "secret_env_key": "GEMINI_API_KEY",
+        "default_base_url": "https://generativelanguage.googleapis.com/v1beta",
+        "default_model": "gemini-2.5-pro",
+        "default_cli_targets": ["gemini"],
+    },
+    "openai_compatible": {
+        "secret_env_key": "OPENAI_API_KEY",
+        "default_base_url": "https://api.openai.com/v1",
+        "default_model": "gpt-5.4-mini",
+        "opencode_package": "@ai-sdk/openai",
+        "default_cli_targets": ["capi", "opencode"],
+    },
+}
+
+AGENT_LAUNCHERS = {
+    "claude": LAUNCHER_ROOT / "0dai-claude-managed",
+    "gemini": LAUNCHER_ROOT / "0dai-gemini-managed",
+    "opencode": LAUNCHER_ROOT / "0dai-opencode-managed",
+    CAPI_AGENT: LAUNCHER_ROOT / "0dai-capi-managed",
+}
+
+UNDERLYING_BINARIES = {
+    "claude": "claude",
+    "gemini": "gemini",
+    "opencode": "opencode",
+    CAPI_AGENT: "opencode",
+}
+
+ENV_KEY_ALIASES = {
+    "GEMINI_API_KEY": ("GOOGLE_API_KEY",),
+}
+
+CLAUDE_AUTH_ENV_KEYS = (
+    "CLAUDE_CONFIG_DIR",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "XDG_STATE_HOME",
+    "XDG_DATA_HOME",
+    "XDG_RUNTIME_DIR",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+)
+CLAUDE_AUTH_STRIP_KEYS = (
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_MODEL",
+)
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S+00:00", time.gmtime())
+
+
+def _canonical_agent_name(agent: str) -> str:
+    normalized = str(agent or "").strip().lower()
+    if normalized in CAPI_AGENT_ALIASES:
+        return CAPI_AGENT
+    return normalized
+
+
+def setup_claude_auth_env(
+    env: dict[str, str] | None = None,
+    *,
+    agent: str = "claude",
+) -> dict[str, str]:
+    """Preserve Claude login state and strip provider auth overrides.
+
+    This is intentionally Claude-only. Subscription auth depends on the
+    interactive ~/.claude login surface, so callers must not reuse it for
+    capi or other provider-backed modes.
+    """
+    canonical = _canonical_agent_name(agent)
+    assert canonical == "claude", f"claude auth setup only supports claude, got {agent}"
+    merged = dict(env or {})
+    for key in CLAUDE_AUTH_STRIP_KEYS:
+        merged.pop(key, None)
+    for key in CLAUDE_AUTH_ENV_KEYS:
+        value = os.environ.get(key, "").strip()
+        if value:
+            merged[key] = value
+    return merged
+
+
+def _normalize_path(path: pathlib.Path | str) -> str:
+    return str(pathlib.Path(path).resolve())
+
+
+def _default_profiles_payload() -> dict[str, Any]:
+    return {"profiles": []}
+
+
+def _default_bindings_payload() -> dict[str, Any]:
+    return {"defaults": {}, "projects": {}}
+
+
+def _ensure_json_parent(path: pathlib.Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _load_json(path: pathlib.Path, default: dict[str, Any]) -> dict[str, Any]:
+    if not path.is_file():
+        return json.loads(json.dumps(default))
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return json.loads(json.dumps(default))
+    if not isinstance(data, dict):
+        return json.loads(json.dumps(default))
+    return data
+
+
+def _write_json(path: pathlib.Path, payload: dict[str, Any]) -> None:
+    _ensure_json_parent(path)
+    path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _safe_slug(text: str) -> str:
+    lowered = re.sub(r"[^a-z0-9]+", "-", str(text or "").strip().lower()).strip("-")
+    return lowered or "profile"
+
+
+def _profile_secret_path(profile_id: str) -> pathlib.Path:
+    return SECRETS_ROOT / f"{profile_id}.env"
+
+
+def _profile_runtime_root(agent: str, profile_id: str) -> pathlib.Path:
+    return RUNTIME_ROOT / _canonical_agent_name(agent) / profile_id
+
+
+def _runtime_home(agent: str, profile_id: str) -> pathlib.Path:
+    return _profile_runtime_root(agent, profile_id) / "home"
+
+
+def _runtime_opencode_config(agent: str, profile_id: str) -> pathlib.Path:
+    return _profile_runtime_root(agent, profile_id) / "opencode.json"
+
+
+def _load_profiles() -> dict[str, Any]:
+    return _load_json(PROFILES_PATH, _default_profiles_payload())
+
+
+def _save_profiles(payload: dict[str, Any]) -> None:
+    _write_json(PROFILES_PATH, payload)
+
+
+def _load_bindings() -> dict[str, Any]:
+    return _load_json(BINDINGS_PATH, _default_bindings_payload())
+
+
+def _save_bindings(payload: dict[str, Any]) -> None:
+    _write_json(BINDINGS_PATH, payload)
+
+
+def _iter_profiles() -> list[dict[str, Any]]:
+    payload = _load_profiles()
+    profiles = payload.get("profiles")
+    if not isinstance(profiles, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for item in profiles:
+        if isinstance(item, dict):
+            out.append(item)
+    return out
+
+
+def _find_profile(profile_id: str) -> dict[str, Any] | None:
+    for profile in _iter_profiles():
+        if str(profile.get("id") or "") == profile_id:
+            return profile
+    return None
+
+
+def _normalize_headers(pairs: list[str]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for raw in pairs:
+        if "=" not in raw:
+            raise ValueError(f"invalid header '{raw}' — use Name=Value")
+        key, value = raw.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            raise ValueError(f"invalid header '{raw}' — header name required")
+        headers[key] = value
+    return headers
+
+
+def _normalize_models(values: list[str]) -> list[str]:
+    models: list[str] = []
+    for raw in values:
+        for part in str(raw or "").split(","):
+            model = part.strip()
+            if model:
+                models.append(model)
+    return sorted(set(models))
+
+
+def _parse_json_object(raw: str, field_name: str) -> dict[str, Any]:
+    text = str(raw or "").strip()
+    if not text:
+        return {}
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{field_name} must be valid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{field_name} must be a JSON object")
+    return payload
+
+
+def _profile_models(profile: dict[str, Any]) -> list[str]:
+    default_model = str(profile.get("default_model") or "").strip()
+    models = []
+    raw_models = profile.get("available_models")
+    if isinstance(raw_models, list):
+        models.extend(str(item).strip() for item in raw_models if str(item).strip())
+    if default_model:
+        models.append(default_model)
+    return sorted(set(models))
+
+
+def _quota_summary(quota: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(quota, dict):
+        return {}
+    keys = (
+        "label",
+        "limit",
+        "limit_reset",
+        "limit_remaining",
+        "include_byok_in_limit",
+        "usage",
+        "usage_daily",
+        "usage_weekly",
+        "usage_monthly",
+        "byok_usage",
+        "byok_usage_daily",
+        "byok_usage_weekly",
+        "byok_usage_monthly",
+        "is_free_tier",
+        "is_management_key",
+        "is_provisioning_key",
+        "expires_at",
+        "rate_limit",
+    )
+    return {key: quota[key] for key in keys if key in quota}
+
+
+def _normalize_cli_targets(
+    provider_kind: str,
+    auth_mode: str,
+    cli_targets: list[str],
+) -> list[str]:
+    normalized = [_canonical_agent_name(item) for item in cli_targets if item]
+    normalized = [item for item in normalized if item in SUPPORTED_AGENTS]
+    if normalized:
+        return sorted(set(normalized))
+    if auth_mode == "native_subscription":
+        return ["claude"]
+    spec = PROVIDER_SPECS[provider_kind]
+    return list(spec.get("default_cli_targets") or [])
+
+
+def _normalize_base_url(provider_kind: str, auth_mode: str, base_url: str) -> str:
+    normalized = str(base_url or "").strip().rstrip("/")
+    if auth_mode == "native_subscription":
+        return ""
+    if normalized:
+        return normalized
+    return str(PROVIDER_SPECS[provider_kind]["default_base_url"])
+
+
+def _invoke_base_url(provider_kind: str, base_url: str) -> str:
+    normalized = str(base_url or "").strip().rstrip("/")
+    if not normalized:
+        return ""
+    if provider_kind in {"anthropic_compatible", "openai_compatible"}:
+        return normalized[: -len("/v1")] if normalized.endswith("/v1") else normalized
+    if provider_kind == "google_ai":
+        return normalized[: -len("/v1beta")] if normalized.endswith("/v1beta") else normalized
+    return normalized
+
+
+# Extra reject net not covered uniformly by ipaddress.is_private across Python
+# versions: RFC 6598 carrier-grade NAT shared address space.
+_CGNAT_NET = ipaddress.ip_network("100.64.0.0/10")
+
+
+def _ip_is_blocked(ip: ipaddress._BaseAddress) -> bool:
+    """True if `ip` points at a non-public destination we must not fetch.
+
+    Collapses IPv4-mapped IPv6 (`::ffff:a.b.c.d`) first so the IPv4 rules apply
+    — without this, is_private/is_loopback return False for the mapped form and
+    the guard is trivially bypassable.
+    """
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    if (
+        ip.is_private
+        or ip.is_loopback
+        or ip.is_link_local  # includes 169.254.0.0/16 → cloud metadata 169.254.169.254
+        or ip.is_reserved
+        or ip.is_multicast
+        or ip.is_unspecified
+    ):
+        return True
+    if isinstance(ip, ipaddress.IPv4Address) and ip in _CGNAT_NET:
+        return True
+    return False
+
+
+def _assert_public_base_url(url: str) -> None:
+    """Reject `url` if its host resolves to any non-public address (SSRF guard).
+
+    Requires http/https, resolves the host via DNS, and blocks the request if
+    ANY resolved IP is private/loopback/link-local/reserved/multicast/
+    unspecified or in the CGNAT range. Defends provider profiles whose
+    user-supplied base_url could otherwise reach internal targets
+    (link-local metadata 169.254.169.254, localhost, redis, etc.) from a
+    free-tier-authenticated request.
+
+    HTTP redirects are covered: _request_json routes through an opener whose
+    redirect handler re-runs this check on every hop, so a public host cannot
+    302 to an internal target.
+
+    SECURITY CAVEAT — this is still a TOCTOU check, not a socket pin.
+    `getaddrinfo` runs here at check time, while the actual socket connect
+    happens later inside urllib, so a DNS-rebind attacker who answers
+    differently for the two lookups can still slip through. Fully closing that
+    hole (pinning the resolved IP into the connect) is out of scope here; this
+    guard raises the bar against the direct internal-URL and redirect-to-
+    internal cases, which are the reported vulnerability. Errors never echo the
+    resolved internal IP back to the caller.
+    """
+    parsed = urllib.parse.urlsplit(str(url or "").strip())
+    scheme = (parsed.scheme or "").lower()
+    if scheme not in {"http", "https"}:
+        raise ValueError(f"base_url scheme must be http or https, got: {scheme or '(none)'}")
+    host = parsed.hostname  # already lowercased, brackets stripped for [::1]
+    if not host:
+        raise ValueError("base_url is missing a host")
+    # Strip any IPv6 zone id (e.g. fe80::1%eth0) before parsing.
+    host_for_ip = host.split("%", 1)[0]
+
+    candidates: list[ipaddress._BaseAddress] = []
+    # If host is already a literal IP, skip DNS entirely.
+    try:
+        candidates.append(ipaddress.ip_address(host_for_ip))
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+        except socket.gaierror as exc:
+            raise ValueError(f"base_url host could not be resolved: {host}") from exc
+        for info in infos:
+            sockaddr = info[4]
+            raw_ip = str(sockaddr[0]).split("%", 1)[0]
+            try:
+                candidates.append(ipaddress.ip_address(raw_ip))
+            except ValueError:
+                # Unparseable address from the resolver — refuse rather than
+                # fall through to an outbound request we cannot vet.
+                raise ValueError(f"base_url host resolved to an unusable address: {host}") from None
+    if not candidates:
+        raise ValueError(f"base_url host could not be resolved: {host}")
+    for ip in candidates:
+        if _ip_is_blocked(ip):
+            # Deliberately do NOT include the resolved IP — avoids leaking the
+            # internal address back to an attacker probing the network.
+            raise ValueError(f"base_url host {host} resolves to a non-public address; refusing request")
+
+
+class _SSRFGuardedRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Re-run the SSRF guard on every redirect target.
+
+    urllib follows 3xx redirects by default, so without this a public host
+    could 302 to an internal address (e.g. the cloud metadata endpoint) and
+    bypass the one-shot pre-request check. Validating each hop closes that
+    bypass while still permitting legitimate public->public redirects.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        # Overrides stdlib HTTPRedirectHandler.redirect_request signature.
+        _assert_public_base_url(newurl)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+# Opener built once; both the SSRF redirect guard and default handlers apply.
+_SSRF_OPENER = urllib.request.build_opener(_SSRFGuardedRedirectHandler())
+
+
+def _default_model(provider_kind: str, requested: str) -> str:
+    normalized = str(requested or "").strip()
+    if normalized:
+        return normalized
+    return str(PROVIDER_SPECS[provider_kind]["default_model"])
+
+
+def _validate_profile_shape(profile: dict[str, Any]) -> None:
+    provider_kind = str(profile.get("provider_kind") or "")
+    auth_mode = str(profile.get("auth_mode") or "")
+    if provider_kind not in PROVIDER_KINDS:
+        raise ValueError(f"unsupported provider_kind: {provider_kind}")
+    if auth_mode not in AUTH_MODES:
+        raise ValueError(f"unsupported auth_mode: {auth_mode}")
+    if auth_mode == "native_subscription":
+        if provider_kind != "anthropic_compatible":
+            raise ValueError("native_subscription is currently supported only for anthropic_compatible")
+    elif not str(profile.get("secret_ref") or "").strip():
+        raise ValueError("secret_ref required for API-key profiles")
+
+
+def _validate_profile_for_agent(profile: dict[str, Any], agent: str) -> None:
+    agent = _canonical_agent_name(agent)
+    provider_kind = str(profile.get("provider_kind") or "")
+    auth_mode = str(profile.get("auth_mode") or "")
+    cli_targets = {str(item) for item in profile.get("cli_targets") or []}
+    if agent not in cli_targets:
+        raise ValueError(f"profile {profile.get('id')} is not enabled for agent {agent}")
+    if agent == "claude":
+        if auth_mode != "native_subscription":
+            raise ValueError("claude managed wrapper currently supports only native_subscription profiles")
+        if provider_kind != "anthropic_compatible":
+            raise ValueError("claude managed wrapper requires anthropic_compatible provider_kind")
+        return
+    if agent == CAPI_AGENT:
+        if provider_kind not in {"anthropic_compatible", "openai_compatible"}:
+            raise ValueError("Claude API Custom requires OpenAI-compatible or Anthropic-compatible profile")
+        if auth_mode not in {"api_key", "api_key_custom_endpoint"}:
+            raise ValueError("Claude API Custom requires API-key profile")
+        return
+    if agent == "gemini":
+        if provider_kind != "google_ai":
+            raise ValueError("gemini wrapper requires google_ai profile")
+        if auth_mode not in {"api_key", "api_key_custom_endpoint"}:
+            raise ValueError("gemini wrapper requires API-key profile")
+        return
+    if agent == "opencode":
+        if provider_kind not in {"anthropic_compatible", "openai_compatible"}:
+            raise ValueError("opencode wrapper supports anthropic_compatible and openai_compatible profiles only")
+        if auth_mode not in {"api_key", "api_key_custom_endpoint"}:
+            raise ValueError("opencode wrapper requires API-key profile")
+        return
+    raise ValueError(f"unsupported agent: {agent}")
+
+
+def _secret_assignments(path: pathlib.Path) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    assignments: dict[str, str] = {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key:
+            assignments[key] = value
+    return assignments
+
+
+def _write_secret_file(path: pathlib.Path, key: str, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f'{key}="{value}"\n', encoding="utf-8")
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _secret_value_from_args(args: argparse.Namespace, secret_env_key: str) -> str:
+    env_name = str(getattr(args, "api_key_env", "") or "").strip()
+    file_name = str(getattr(args, "api_key_file", "") or "").strip()
+    if env_name:
+        value = str(os.environ.get(env_name) or "").strip()
+        if not value:
+            raise ValueError(f"environment variable {env_name} is empty")
+        return value
+    if file_name:
+        try:
+            value = pathlib.Path(file_name).read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise ValueError(f"failed to read {file_name}: {exc}") from exc
+        if not value:
+            raise ValueError(f"file {file_name} is empty")
+        return value
+    prompt = f"Enter {secret_env_key}: "
+    value = getpass.getpass(prompt).strip()
+    if not value:
+        raise ValueError(f"{secret_env_key} is required")
+    return value
+
+
+def _project_bindings_for(target: pathlib.Path) -> dict[str, str]:
+    bindings = _load_bindings()
+    projects = bindings.get("projects")
+    if not isinstance(projects, dict):
+        return {}
+    value = projects.get(_normalize_path(target))
+    return value if isinstance(value, dict) else {}
+
+
+def resolve_bound_profile_id(target: pathlib.Path | None, agent: str) -> str:
+    agent = _canonical_agent_name(agent)
+    bindings = _load_bindings()
+    if target is not None:
+        project_overrides = _project_bindings_for(target)
+        if agent in project_overrides:
+            return str(project_overrides.get(agent) or "")
+    defaults = bindings.get("defaults")
+    if isinstance(defaults, dict):
+        return str(defaults.get(agent) or "")
+    return ""
+
+
+def _legacy_capi_profile() -> dict[str, Any] | None:
+    try:
+        import capi_profile_guard
+    except ImportError:
+        return None
+    env_path = capi_profile_guard.ENV_FILE
+    assignments = _secret_assignments(env_path)
+    secret_key = str(assignments.get("CAPI_SECRET_ENV_KEY") or "").strip()
+    if not secret_key:
+        secret_key = "OPENAI_API_KEY" if assignments.get("OPENAI_API_KEY") else "ANTHROPIC_API_KEY"
+    provider_kind = str(assignments.get("CAPI_PROVIDER_KIND") or "").strip()
+    if provider_kind not in PROVIDER_KINDS:
+        provider_kind = (
+            "openai_compatible"
+            if secret_key.startswith("OPENAI") or secret_key.startswith("OPENROUTER")
+            else "anthropic_compatible"
+        )
+    api_key = str(assignments.get(secret_key) or "").strip()
+    if not api_key:
+        return None
+    upstream = str(assignments.get(capi_profile_guard.UPSTREAM_ENV_KEY) or "").strip().rstrip("/")
+    spec = PROVIDER_SPECS[provider_kind]
+    return {
+        "id": "__legacy_capi__",
+        "name": "Legacy Custom API",
+        "provider_kind": provider_kind,
+        "auth_mode": "api_key_custom_endpoint",
+        "base_url": upstream or str(spec["default_base_url"]),
+        "default_model": str(spec["default_model"]),
+        "headers": {},
+        "cli_targets": [CAPI_AGENT],
+        "secret_env_key": secret_key,
+        "secret_ref": "",
+        "_secret_value": api_key,
+        "status": "legacy-fallback",
+    }
+
+
+def resolve_profile(target: pathlib.Path | None, agent: str) -> dict[str, Any] | None:
+    agent = _canonical_agent_name(agent)
+    profile_id = resolve_bound_profile_id(target, agent)
+    if profile_id:
+        profile = _find_profile(profile_id)
+        if not profile:
+            raise ValueError(f"bound profile not found: {profile_id}")
+        _validate_profile_shape(profile)
+        _validate_profile_for_agent(profile, agent)
+        return dict(profile)
+    if agent == CAPI_AGENT:
+        return _legacy_capi_profile()
+    return None
+
+
+def _secret_value(profile: dict[str, Any]) -> str:
+    inline = str(profile.get("_secret_value") or "").strip()
+    if inline:
+        return inline
+    secret_ref = str(profile.get("secret_ref") or "").strip()
+    if not secret_ref:
+        return ""
+    path = _profile_secret_path(str(profile.get("id") or ""))
+    return str(_secret_assignments(path).get(str(profile.get("secret_env_key") or "")) or "").strip()
+
+
+def _runtime_dirs_for(agent: str, profile_id: str) -> dict[str, pathlib.Path]:
+    runtime_root = _profile_runtime_root(agent, profile_id)
+    home = runtime_root / "home"
+    return {
+        "root": runtime_root,
+        "home": home,
+        "config": home / ".config",
+        "cache": home / ".cache",
+        "state": home / ".local" / "state",
+        "data": home / ".local" / "share",
+    }
+
+
+def _normalize_opencode_base_url(profile: dict[str, Any]) -> str:
+    base_url = str(profile.get("base_url") or "").strip().rstrip("/")
+    if not base_url:
+        return ""
+    if base_url.endswith("/v1") or base_url.endswith("/v1beta"):
+        return base_url
+    if str(profile.get("provider_kind") or "") == "google_ai":
+        return f"{base_url}/v1beta"
+    return f"{base_url}/v1"
+
+
+def _opencode_model_id(profile: dict[str, Any], agent: str) -> str:
+    canonical_agent = _canonical_agent_name(agent)
+    provider_id = "capi" if canonical_agent == CAPI_AGENT else str(profile.get("id") or "provider")
+    model = str(profile.get("default_model") or "").strip() or str(PROVIDER_SPECS[str(profile.get("provider_kind") or "")]["default_model"])
+    if canonical_agent == CAPI_AGENT:
+        return model if model.startswith(f"{provider_id}/") else f"{provider_id}/{model}"
+    if "/" in model:
+        return model
+    return f"{provider_id}/{model}"
+
+
+def _opencode_provider_block(profile: dict[str, Any], agent: str) -> tuple[str, dict[str, Any]]:
+    provider_kind = str(profile.get("provider_kind") or "")
+    spec = PROVIDER_SPECS[provider_kind]
+    provider_id = "capi" if _canonical_agent_name(agent) == CAPI_AGENT else str(profile.get("id") or "provider")
+    options: dict[str, Any] = {
+        "apiKey": "{env:%s}" % str(profile.get("secret_env_key") or spec["secret_env_key"]),
+        "timeout": 120000,
+        "chunkTimeout": 30000,
+    }
+    base_url = _normalize_opencode_base_url(profile)
+    if base_url:
+        options["baseURL"] = base_url
+    headers = profile.get("headers") if isinstance(profile.get("headers"), dict) else {}
+    if headers:
+        options["headers"] = headers
+    package = spec.get("opencode_package")
+    if not package:
+        raise ValueError(f"provider kind {provider_kind} is not supported for OpenCode-backed runtime")
+    model_names = _profile_models(profile)
+    block = {
+        "npm": package,
+        "name": str(profile.get("name") or provider_id),
+        "options": options,
+        "models": {model: {"name": model} for model in model_names},
+    }
+    return provider_id, block
+
+
+def _write_opencode_config(path: pathlib.Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def _prepare_opencode_runtime(profile: dict[str, Any], agent: str) -> dict[str, Any]:
+    profile_id = str(profile.get("id") or "provider")
+    dirs = _runtime_dirs_for(agent, profile_id)
+    for key in ("config", "cache", "state", "data"):
+        dirs[key].mkdir(parents=True, exist_ok=True)
+    config_path = _runtime_opencode_config(agent, profile_id)
+    provider_id, provider_block = _opencode_provider_block(profile, agent)
+    config_payload = {
+        "$schema": SCHEMA_URL,
+        "autoupdate": False,
+        "enabled_providers": [provider_id],
+        "model": _opencode_model_id(profile, agent),
+        "provider": {provider_id: provider_block},
+    }
+    _write_opencode_config(config_path, config_payload)
+    return {
+        "config_path": str(config_path),
+        "provider_id": provider_id,
+        "home": dirs["home"],
+        "config": dirs["config"],
+        "cache": dirs["cache"],
+        "state": dirs["state"],
+        "data": dirs["data"],
+    }
+
+
+def _prepare_gemini_runtime(profile: dict[str, Any], agent: str) -> dict[str, Any]:
+    profile_id = str(profile.get("id") or "provider")
+    dirs = _runtime_dirs_for(agent, profile_id)
+    for key in ("config", "cache", "state", "data"):
+        dirs[key].mkdir(parents=True, exist_ok=True)
+    gemini_dir = dirs["home"] / ".gemini"
+    gemini_env = gemini_dir / ".env"
+    settings_path = gemini_dir / "settings.json"
+    gemini_dir.mkdir(parents=True, exist_ok=True)
+    model_name = str(profile.get("default_model") or PROVIDER_SPECS["google_ai"]["default_model"])
+    _write_json(
+        settings_path,
+        {
+            "managed": True,
+            "model": {"name": model_name},
+            "general": {"defaultApprovalMode": GEMINI_DEFAULT_APPROVAL_MODE},
+        },
+    )
+    secret_key = str(profile.get("secret_env_key") or PROVIDER_SPECS["google_ai"]["secret_env_key"])
+    secret_value = _secret_value(profile)
+    if secret_value:
+        gemini_env.write_text(
+            f'{secret_key}="{secret_value}"\nGOOGLE_API_KEY="{secret_value}"\n',
+            encoding="utf-8",
+        )
+    return {
+        "home": dirs["home"],
+        "config": dirs["config"],
+        "cache": dirs["cache"],
+        "state": dirs["state"],
+        "data": dirs["data"],
+        "gemini_env": str(gemini_env),
+        "settings_path": str(settings_path),
+        "default_approval_mode": GEMINI_DEFAULT_APPROVAL_MODE,
+    }
+
+
+def resolve_runtime(target: pathlib.Path, agent: str) -> dict[str, Any]:
+    agent = _canonical_agent_name(agent)
+    binary = UNDERLYING_BINARIES.get(agent)
+    if not binary:
+        raise ValueError(f"unsupported agent: {agent}")
+    resolved = shutil.which(binary)
+    if not resolved:
+        raise ValueError(f"{binary} binary not found on PATH")
+    profile = resolve_profile(target, agent)
+    env = dict(os.environ)
+    metadata: dict[str, Any] = {
+        "agent": agent,
+        "binary": resolved,
+        "profile_id": str(profile.get("id") or "") if profile else "",
+        "provider_kind": str(profile.get("provider_kind") or "") if profile else "",
+        "auth_mode": str(profile.get("auth_mode") or "") if profile else "",
+        "runtime_backend": "",
+        "provider_model": "",
+        "secret_env_key": str(profile.get("secret_env_key") or "") if profile else "",
+        "available_models": _profile_models(profile) if profile else [],
+        "key_quota": profile.get("key_quota") if profile else {},
+    }
+    if agent == "claude":
+        env = setup_claude_auth_env(env, agent=agent)
+    if not profile:
+        return {"binary": resolved, "env": env, "argv_prefix": [], "metadata": metadata}
+
+    _validate_profile_for_agent(profile, agent)
+    metadata["profile_name"] = str(profile.get("name") or "")
+    metadata["runtime_backend"] = "provider-profile"
+    metadata["provider_model"] = str(profile.get("default_model") or "")
+    if agent == "claude":
+        # Native claude sessions stay on /root/.claude/.credentials.json
+        # subscription OAuth. Strip poisoned ANTHROPIC_* vars so a RuAPI-
+        # backed parent shell cannot override the login path.
+        for k in ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL"):
+            env.pop(k, None)
+        return {"binary": resolved, "env": env, "argv_prefix": [], "metadata": metadata}
+
+    secret_value = _secret_value(profile)
+    secret_env_key = str(profile.get("secret_env_key") or "")
+    if not secret_value:
+        raise ValueError(f"profile {profile.get('id')} is missing {secret_env_key}")
+    env[secret_env_key] = secret_value
+    for alias in ENV_KEY_ALIASES.get(secret_env_key, ()):
+        env[alias] = secret_value
+
+    if agent == "gemini":
+        runtime = _prepare_gemini_runtime(profile, agent)
+        env.update(
+            {
+                "HOME": str(runtime["home"]),
+                "XDG_CONFIG_HOME": str(runtime["config"]),
+                "XDG_CACHE_HOME": str(runtime["cache"]),
+                "XDG_STATE_HOME": str(runtime["state"]),
+                "XDG_DATA_HOME": str(runtime["data"]),
+            }
+        )
+        metadata.update(runtime)
+        return {"binary": resolved, "env": env, "argv_prefix": [], "metadata": metadata}
+
+    runtime = _prepare_opencode_runtime(profile, agent)
+    env.update(
+        {
+            "HOME": str(runtime["home"]),
+            "XDG_CONFIG_HOME": str(runtime["config"]),
+            "XDG_CACHE_HOME": str(runtime["cache"]),
+            "XDG_STATE_HOME": str(runtime["state"]),
+            "XDG_DATA_HOME": str(runtime["data"]),
+            "OPENCODE_CONFIG": str(runtime["config_path"]),
+        }
+    )
+    metadata.update(runtime)
+    return {"binary": resolved, "env": env, "argv_prefix": [], "metadata": metadata}
+
+
+def runtime_metadata_for_target(target: pathlib.Path | None, agent: str) -> dict[str, Any]:
+    if target is None:
+        return {}
+    try:
+        runtime = resolve_runtime(pathlib.Path(target).resolve(), agent)
+    except Exception:  # noqa: BLE001 — resolve_runtime failed
+        return {}
+    metadata = runtime.get("metadata")
+    return dict(metadata) if isinstance(metadata, dict) else {}
+
+
+def wrapper_path(agent: str) -> pathlib.Path:
+    agent = _canonical_agent_name(agent)
+    path = AGENT_LAUNCHERS.get(agent)
+    if not path:
+        raise ValueError(f"unsupported agent: {agent}")
+    return path
+
+
+def ensure_agent_wrapper(agent: str) -> pathlib.Path:
+    agent = _canonical_agent_name(agent)
+    path = wrapper_path(agent)
+    script = (
+        "#!/usr/bin/env bash\n"
+        "set -euo pipefail\n"
+        f'exec python3 "{SCRIPT_PATH}" exec --agent "{agent}" --cwd "${{ODAI_PROVIDER_CWD:-$PWD}}" -- "$@"\n'
+    )
+    current = ""
+    try:
+        current = path.read_text(encoding="utf-8") if path.is_file() else ""
+    except OSError:
+        current = ""
+    if current != script:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(script, encoding="utf-8")
+        path.chmod(0o755)
+    return path
+
+
+def ensure_wrappers() -> list[pathlib.Path]:
+    return [ensure_agent_wrapper(agent) for agent in AGENT_LAUNCHERS]
+
+
+def cmd_exec(args: argparse.Namespace) -> int:
+    agent = _canonical_agent_name(args.agent)
+    target = pathlib.Path(args.cwd or os.getcwd()).resolve()
+    runtime = resolve_runtime(target, agent)
+    argv = list(args.argv or [])
+    if argv and argv[0] == "--":
+        argv = argv[1:]
+    binary = str(runtime["binary"])
+    os.execvpe(binary, [binary, *argv], runtime["env"])
+    return 0
+
+
+def _masked_path(path: pathlib.Path) -> str:
+    return str(path).replace(str(pathlib.Path.home()), "~")
+
+
+def cmd_profile_add(args: argparse.Namespace) -> int:
+    provider_kind = str(args.provider_kind or "").strip()
+    auth_mode = str(args.auth_mode or "").strip()
+    if provider_kind not in PROVIDER_KINDS:
+        raise SystemExit(f"unsupported provider-kind: {provider_kind}")
+    if auth_mode not in AUTH_MODES:
+        raise SystemExit(f"unsupported auth-mode: {auth_mode}")
+    if auth_mode == "native_subscription" and provider_kind != "anthropic_compatible":
+        raise SystemExit("native_subscription is supported only for anthropic_compatible in v1")
+
+    profiles_payload = _load_profiles()
+    profiles = [item for item in profiles_payload.get("profiles", []) if isinstance(item, dict)]
+    base_id = _safe_slug(args.name)
+    profile_id = base_id
+    existing_ids = {str(item.get("id") or "") for item in profiles}
+    counter = 2
+    while profile_id in existing_ids:
+        profile_id = f"{base_id}-{counter}"
+        counter += 1
+
+    spec = PROVIDER_SPECS[provider_kind]
+    cli_targets = _normalize_cli_targets(provider_kind, auth_mode, args.cli_target)
+    secret_env_key = str(args.secret_env_key or spec["secret_env_key"]).strip()
+    available_models = _normalize_models(args.available_model)
+    key_quota = _parse_json_object(args.quota_json, "--quota-json")
+    profile = {
+        "id": profile_id,
+        "name": str(args.name or profile_id),
+        "provider_kind": provider_kind,
+        "auth_mode": auth_mode,
+        "base_url": _normalize_base_url(provider_kind, auth_mode, args.base_url),
+        "default_model": _default_model(provider_kind, args.model),
+        "headers": _normalize_headers(args.header),
+        "cli_targets": cli_targets,
+        "secret_env_key": secret_env_key,
+        "secret_ref": f"{profile_id}.env" if auth_mode != "native_subscription" else "",
+        "status": "active",
+        "created_at": _now(),
+        "updated_at": _now(),
+    }
+    if available_models:
+        profile["available_models"] = available_models
+        profile["model_catalog"] = {
+            "source": "manual",
+            "updated_at": _now(),
+            "count": len(available_models),
+        }
+    if key_quota:
+        profile["quota"] = _quota_summary(key_quota)
+        profile["key_quota"] = {
+            "source": "manual",
+            "updated_at": _now(),
+            "data": _quota_summary(key_quota),
+        }
+    _validate_profile_shape(profile)
+    if auth_mode != "native_subscription":
+        secret_value = _secret_value_from_args(args, secret_env_key)
+        _write_secret_file(_profile_secret_path(profile_id), secret_env_key, secret_value)
+    profiles.append(profile)
+    profiles_payload["profiles"] = sorted(profiles, key=lambda item: str(item.get("name") or item.get("id") or ""))
+    _save_profiles(profiles_payload)
+    ensure_wrappers()
+    print(f"created profile: {profile_id}")
+    print(f"  provider: {provider_kind}")
+    print(f"  auth:     {auth_mode}")
+    print(f"  targets:  {', '.join(cli_targets) if cli_targets else 'none'}")
+    if profile["secret_ref"]:
+        print(f"  secret:   {_masked_path(_profile_secret_path(profile_id))}")
+    return 0
+
+
+def cmd_profile_list(args: argparse.Namespace) -> int:
+    profiles = _iter_profiles()
+    if args.json:
+        print(json.dumps({"profiles": profiles}, indent=2, ensure_ascii=False))
+        return 0
+    if not profiles:
+        print("No provider profiles yet. Add one with: 0dai provider profile add --name my-profile ...")
+        return 0
+    print(f"Provider profiles ({len(profiles)})")
+    print("ID                      Name                     Kind                   Auth                     Models  Targets")
+    print("-" * 126)
+    for profile in profiles:
+        model_count = len(_profile_models(profile))
+        print(
+            f"{str(profile.get('id') or '')[:22].ljust(22)}  "
+            f"{str(profile.get('name') or '')[:23].ljust(23)}  "
+            f"{str(profile.get('provider_kind') or '')[:22].ljust(22)}  "
+            f"{str(profile.get('auth_mode') or '')[:24].ljust(24)}  "
+            f"{str(model_count).rjust(6)}  "
+            f"{','.join(profile.get('cli_targets') or [])}"
+        )
+    return 0
+
+
+def cmd_profile_show(args: argparse.Namespace) -> int:
+    profile = _find_profile(args.profile_id)
+    if not profile:
+        raise SystemExit(f"profile not found: {args.profile_id}")
+    payload = dict(profile)
+    if payload.get("secret_ref"):
+        payload["secret_path"] = str(_profile_secret_path(str(profile.get("id") or "")))
+    if args.json:
+        print(json.dumps({"profile": payload}, indent=2, ensure_ascii=False))
+        return 0
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+    return 0
+
+
+def _extract_text(provider_kind: str, payload: dict[str, Any]) -> str:
+    if provider_kind == "anthropic_compatible":
+        content = payload.get("content")
+        if isinstance(content, list):
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    return str(item.get("text") or "")
+        return ""
+    if provider_kind == "openai_compatible":
+        choices = payload.get("choices")
+        if isinstance(choices, list) and choices:
+            first = choices[0]
+            if isinstance(first, dict):
+                message = first.get("message")
+                if isinstance(message, dict):
+                    return str(message.get("content") or "")
+        return ""
+    if provider_kind == "google_ai":
+        candidates = payload.get("candidates")
+        if isinstance(candidates, list) and candidates:
+            first = candidates[0]
+            if isinstance(first, dict):
+                content = first.get("content")
+                if isinstance(content, dict):
+                    parts = content.get("parts")
+                    if isinstance(parts, list):
+                        for part in parts:
+                            if isinstance(part, dict) and str(part.get("text") or "").strip():
+                                return str(part.get("text") or "")
+        return ""
+    return ""
+
+
+def _request_json(
+    url: str,
+    *,
+    method: str = "GET",
+    headers: dict[str, str] | None = None,
+    payload: dict[str, Any] | None = None,
+    timeout: int = REQUEST_TIMEOUT_SECONDS,
+) -> tuple[int, dict[str, Any], str]:
+    # SSRF guard at the outbound chokepoint: every provider fetch/invoke goes
+    # through here, so this defends the stored-then-fetched flow even when a
+    # malicious base_url slipped past add-time validation. The opener below
+    # re-validates every redirect hop (see _SSRFGuardedRedirectHandler).
+    _assert_public_base_url(url)
+    body = None
+    if payload is not None:
+        body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=body, method=method)
+    final_headers = dict(DEFAULT_HEADERS)
+    final_headers.update(headers or {})
+    if body is not None:
+        final_headers.setdefault("Content-Type", "application/json")
+    for key, value in final_headers.items():
+        req.add_header(key, value)
+    try:
+        with _SSRF_OPENER.open(req, timeout=timeout) as response:
+            raw = response.read().decode("utf-8")
+            parsed = json.loads(raw) if raw else {}
+            return int(response.status), parsed if isinstance(parsed, dict) else {}, raw
+    except urllib.error.HTTPError as exc:
+        raw = exc.read().decode("utf-8", errors="replace")
+        try:
+            parsed = json.loads(raw) if raw else {}
+        except json.JSONDecodeError:
+            parsed = {}
+        return int(exc.code), parsed if isinstance(parsed, dict) else {}, raw
+
+
+def _auth_headers_for_profile(profile: dict[str, Any], secret_value: str) -> dict[str, str]:
+    provider_kind = str(profile.get("provider_kind") or "")
+    headers = dict(profile.get("headers") or {})
+    if provider_kind == "anthropic_compatible":
+        headers.update(
+            {
+                "x-api-key": secret_value,
+                "anthropic-version": "2023-06-01",
+            }
+        )
+    elif provider_kind == "openai_compatible":
+        headers.update({"Authorization": f"Bearer {secret_value}"})
+    elif provider_kind == "google_ai":
+        headers.update(
+            {
+                "x-goog-api-key": secret_value,
+                "x-goog-api-client": GOOGLE_API_CLIENT,
+            }
+        )
+    return headers
+
+
+def _extract_model_ids(provider_kind: str, payload: dict[str, Any]) -> list[str]:
+    if provider_kind in {"anthropic_compatible", "openai_compatible"}:
+        data = payload.get("data")
+        if not isinstance(data, list):
+            return []
+        models: list[str] = []
+        for item in data:
+            if isinstance(item, dict):
+                model_id = str(item.get("id") or "").strip()
+                if model_id:
+                    models.append(model_id)
+        return sorted(set(models))
+    if provider_kind == "google_ai":
+        data = payload.get("models")
+        if not isinstance(data, list):
+            return []
+        models = []
+        for item in data:
+            if isinstance(item, dict):
+                model_id = str(item.get("name") or "").strip()
+                if model_id.startswith("models/"):
+                    model_id = model_id[len("models/") :]
+                if model_id:
+                    models.append(model_id)
+        return sorted(set(models))
+    return []
+
+
+def fetch_profile_capabilities(profile: dict[str, Any]) -> dict[str, Any]:
+    provider_kind = str(profile.get("provider_kind") or "")
+    secret_key = str(profile.get("secret_env_key") or "")
+    secret_value = _secret_value(profile)
+    if not secret_value:
+        raise ValueError(f"profile {profile.get('id')} is missing {secret_key}")
+    base_url = _invoke_base_url(provider_kind, str(profile.get("base_url") or ""))
+    if not base_url:
+        raise ValueError(f"profile {profile.get('id')} has no base_url")
+    headers = _auth_headers_for_profile(profile, secret_value)
+    result: dict[str, Any] = {
+        "fetched_at": _now(),
+        "available_models": [],
+        "model_catalog": {},
+        "quota": {},
+        "key_quota": {},
+        "errors": [],
+    }
+
+    if provider_kind == "google_ai":
+        models_url = f"{base_url}/v1beta/models"
+    else:
+        models_url = f"{base_url}/v1/models"
+    status, payload, raw = _request_json(models_url, headers=headers)
+    if status >= 200 and status < 300:
+        models = _extract_model_ids(provider_kind, payload)
+        result["available_models"] = models
+        result["model_catalog"] = {
+            "source": models_url,
+            "updated_at": result["fetched_at"],
+            "count": len(models),
+        }
+    else:
+        result["errors"].append(
+            {
+                "kind": "models",
+                "status": status,
+                "source": models_url,
+                "message": raw[:500],
+            }
+        )
+
+    if provider_kind == "openai_compatible" and "openrouter.ai" in base_url:
+        quota_url = f"{base_url}/v1/key"
+        status, payload, raw = _request_json(quota_url, headers=headers)
+        if status >= 200 and status < 300 and isinstance(payload.get("data"), dict):
+            quota = _quota_summary(payload["data"])
+            result["quota"] = quota
+            result["key_quota"] = {
+                "source": quota_url,
+                "updated_at": result["fetched_at"],
+                "data": quota,
+            }
+        else:
+            result["errors"].append(
+                {
+                    "kind": "quota",
+                    "status": status,
+                    "source": quota_url,
+                    "message": raw[:500],
+                }
+            )
+    return result
+
+
+def cmd_profile_refresh(args: argparse.Namespace) -> int:
+    profile = _find_profile(args.profile_id)
+    if not profile:
+        raise SystemExit(f"profile not found: {args.profile_id}")
+    try:
+        snapshot = fetch_profile_capabilities(profile)
+    except Exception as exc:  # noqa: BLE001 — CLI top-level guard: network fetch failure → exit 1
+        payload = {"ok": False, "error": str(exc)}
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 1
+
+    profiles_payload = _load_profiles()
+    for item in profiles_payload.get("profiles", []):
+        if not isinstance(item, dict) or str(item.get("id") or "") != args.profile_id:
+            continue
+        if snapshot.get("available_models"):
+            item["available_models"] = snapshot["available_models"]
+            item["model_catalog"] = snapshot["model_catalog"]
+        if snapshot.get("quota"):
+            item["quota"] = snapshot["quota"]
+            item["key_quota"] = snapshot["key_quota"]
+        item["capability_refreshed_at"] = snapshot["fetched_at"]
+        errors = snapshot.get("errors") if isinstance(snapshot.get("errors"), list) else []
+        if errors:
+            item["capability_errors"] = errors
+        else:
+            item.pop("capability_errors", None)
+        item["updated_at"] = _now()
+    _save_profiles(profiles_payload)
+
+    payload = {
+        "ok": not bool(snapshot.get("errors")),
+        "profile_id": args.profile_id,
+        "available_model_count": len(snapshot.get("available_models") or []),
+        "quota_present": bool(snapshot.get("quota")),
+        "errors": snapshot.get("errors") or [],
+    }
+    if args.json:
+        payload["available_models"] = snapshot.get("available_models") or []
+        payload["quota"] = snapshot.get("quota") or {}
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0 if payload["ok"] else 1
+    print(
+        f"refreshed {args.profile_id}: "
+        f"models={payload['available_model_count']} "
+        f"quota={'yes' if payload['quota_present'] else 'no'}"
+    )
+    if payload["errors"]:
+        print(json.dumps({"errors": payload["errors"]}, indent=2, ensure_ascii=False))
+        return 1
+    return 0
+
+
+def invoke_profile(
+    profile: dict[str, Any],
+    *,
+    prompt: str,
+    model: str = "",
+    max_tokens: int = 128,
+) -> dict[str, Any]:
+    provider_kind = str(profile.get("provider_kind") or "")
+    auth_mode = str(profile.get("auth_mode") or "")
+    if auth_mode == "native_subscription":
+        raise ValueError("provider invoke does not support native_subscription profiles")
+    secret_key = str(profile.get("secret_env_key") or "")
+    secret_value = _secret_value(profile)
+    if not secret_value:
+        raise ValueError(f"profile {profile.get('id')} is missing {secret_key}")
+    headers = dict(profile.get("headers") or {})
+    model_name = str(model or profile.get("default_model") or "").strip()
+    base_url = _invoke_base_url(provider_kind, str(profile.get("base_url") or ""))
+    if provider_kind == "anthropic_compatible":
+        headers.update(
+            {
+                "x-api-key": secret_value,
+                "anthropic-version": "2023-06-01",
+            }
+        )
+        status, payload, raw = _request_json(
+            f"{base_url}/v1/messages",
+            method="POST",
+            headers=headers,
+            payload={
+                "model": model_name,
+                "max_tokens": max_tokens,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+        )
+    elif provider_kind == "openai_compatible":
+        headers.update({"Authorization": f"Bearer {secret_value}"})
+        status, payload, raw = _request_json(
+            f"{base_url}/v1/chat/completions",
+            method="POST",
+            headers=headers,
+            payload={
+                "model": model_name,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": max_tokens,
+            },
+        )
+    elif provider_kind == "google_ai":
+        headers.update(
+            {
+                "x-goog-api-key": secret_value,
+                "x-goog-api-client": GOOGLE_API_CLIENT,
+            }
+        )
+        status, payload, raw = _request_json(
+            f"{base_url}/v1beta/models/{model_name}:generateContent",
+            method="POST",
+            headers=headers,
+            payload={
+                "contents": [
+                    {
+                        "parts": [{"text": prompt}],
+                    }
+                ]
+            },
+        )
+    else:
+        raise ValueError(f"unsupported provider_kind: {provider_kind}")
+    return {
+        "status": status,
+        "payload": payload,
+        "raw": raw,
+        "text": _extract_text(provider_kind, payload),
+    }
+
+
+def cmd_profile_test(args: argparse.Namespace) -> int:
+    profile = _find_profile(args.profile_id)
+    if not profile:
+        raise SystemExit(f"profile not found: {args.profile_id}")
+    try:
+        result = invoke_profile(
+            profile,
+            prompt=DEFAULT_TEST_PROMPT,
+            model=args.model or str(profile.get("default_model") or ""),
+            max_tokens=24,
+        )
+    except Exception as exc:  # noqa: BLE001 — CLI top-level guard: network invoke failure → exit 1
+        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 1
+    ok = result["status"] >= 200 and result["status"] < 300 and str(result.get("text") or "").strip()
+    payload = {
+        "ok": ok,
+        "status": result["status"],
+        "text": str(result.get("text") or "").strip(),
+        "payload": result["payload"] if args.json else {},
+    }
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+    profiles_payload = _load_profiles()
+    for item in profiles_payload.get("profiles", []):
+        if isinstance(item, dict) and str(item.get("id") or "") == args.profile_id:
+            item["last_tested_at"] = _now()
+            item["last_test_status"] = "ok" if ok else "failed"
+    _save_profiles(profiles_payload)
+    return 0 if ok else 1
+
+
+def cmd_bind(args: argparse.Namespace) -> int:
+    profile = _find_profile(args.profile_id)
+    if not profile:
+        raise SystemExit(f"profile not found: {args.profile_id}")
+    agent = _canonical_agent_name(args.agent)
+    if agent not in SUPPORTED_AGENTS:
+        raise SystemExit(f"unsupported agent: {args.agent}")
+    _validate_profile_shape(profile)
+    _validate_profile_for_agent(profile, agent)
+    bindings = _load_bindings()
+    if args.default or not args.target:
+        defaults = bindings.setdefault("defaults", {})
+        if not isinstance(defaults, dict):
+            defaults = {}
+            bindings["defaults"] = defaults
+        defaults[agent] = args.profile_id
+        scope = "account default"
+    else:
+        projects = bindings.setdefault("projects", {})
+        if not isinstance(projects, dict):
+            projects = {}
+            bindings["projects"] = projects
+        key = _normalize_path(pathlib.Path(args.target))
+        entry = projects.setdefault(key, {})
+        if not isinstance(entry, dict):
+            entry = {}
+            projects[key] = entry
+        entry[agent] = args.profile_id
+        scope = key
+    _save_bindings(bindings)
+    ensure_wrappers()
+    print(f"bound {agent} -> {args.profile_id} ({scope})")
+    return 0
+
+
+def cmd_bindings(args: argparse.Namespace) -> int:
+    target = pathlib.Path(args.target).resolve() if args.target else None
+    bindings = _load_bindings()
+    defaults = bindings.get("defaults") if isinstance(bindings.get("defaults"), dict) else {}
+    projects = bindings.get("projects") if isinstance(bindings.get("projects"), dict) else {}
+    payload = {
+        "defaults": defaults,
+        "resolved": {},
+        "project": _normalize_path(target) if target else "",
+        "project_overrides": projects.get(_normalize_path(target)) if target else {},
+    }
+    if target is not None:
+        payload["resolved"] = {
+            agent: resolve_bound_profile_id(target, agent)
+            for agent in sorted(SUPPORTED_AGENTS)
+        }
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0
+    print("Provider bindings")
+    if defaults:
+        print("  defaults:")
+        for agent, profile_id in sorted(defaults.items()):
+            print(f"    {agent}: {profile_id}")
+    else:
+        print("  defaults: none")
+    if target is not None:
+        print(f"  project: {_normalize_path(target)}")
+        project_overrides = payload.get("project_overrides") or {}
+        if project_overrides:
+            for agent, profile_id in sorted(project_overrides.items()):
+                print(f"    override {agent}: {profile_id}")
+        print("  resolved:")
+        for agent, profile_id in sorted((payload.get("resolved") or {}).items()):
+            print(f"    {agent}: {profile_id or '—'}")
+    return 0
+
+
+def cmd_invoke(args: argparse.Namespace) -> int:
+    profile: dict[str, Any] | None = None
+    if args.profile_id:
+        profile = _find_profile(args.profile_id)
+        if not profile:
+            raise SystemExit(f"profile not found: {args.profile_id}")
+    elif args.agent and args.target:
+        profile = resolve_profile(pathlib.Path(args.target).resolve(), args.agent)
+        if not profile:
+            raise SystemExit(f"no bound profile for {args.agent} in {args.target}")
+    else:
+        raise SystemExit("provide --profile or (--agent and --target)")
+    try:
+        result = invoke_profile(
+            profile,
+            prompt=args.prompt,
+            model=args.model or str(profile.get("default_model") or ""),
+            max_tokens=args.max_tokens,
+        )
+    except Exception as exc:  # noqa: BLE001 — CLI top-level guard: network invoke failure → exit 1
+        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 1
+    payload = {
+        "ok": result["status"] >= 200 and result["status"] < 300,
+        "status": result["status"],
+        "text": result["text"],
+    }
+    if args.json:
+        payload["payload"] = result["payload"]
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0 if payload["ok"] else 1
+    if payload["ok"]:
+        print(str(payload["text"]).strip())
+        return 0
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+    return 1
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    target = pathlib.Path(args.target).resolve()
+    payload = {
+        "target": _normalize_path(target),
+        "bindings": {
+            agent: resolve_bound_profile_id(target, agent)
+            for agent in sorted(SUPPORTED_AGENTS)
+        },
+        "profiles": [
+            {
+                "id": profile.get("id"),
+                "name": profile.get("name"),
+                "provider_kind": profile.get("provider_kind"),
+                "auth_mode": profile.get("auth_mode"),
+                "targets": profile.get("cli_targets"),
+                "available_model_count": len(_profile_models(profile)),
+                "quota": profile.get("quota") or {},
+                "last_test_status": profile.get("last_test_status"),
+            }
+            for profile in _iter_profiles()
+        ],
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0
+    print(f"Provider status for {payload['target']}")
+    for agent, profile_id in sorted(payload["bindings"].items()):
+        print(f"  {agent}: {profile_id or '—'}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="0dai provider")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    profile = sub.add_parser("profile", help="Manage provider profiles")
+    profile_sub = profile.add_subparsers(dest="profile_command", required=True)
+
+    add = profile_sub.add_parser("add", help="Add a local provider profile")
+    add.add_argument("--name", required=True)
+    add.add_argument("--provider-kind", required=True, choices=sorted(PROVIDER_KINDS))
+    add.add_argument("--auth-mode", required=True, choices=sorted(AUTH_MODES))
+    add.add_argument("--base-url", default="")
+    add.add_argument("--model", default="")
+    add.add_argument("--available-model", action="append", default=[])
+    add.add_argument("--quota-json", default="")
+    add.add_argument("--api-key-file", default="")
+    add.add_argument("--api-key-env", default="")
+    add.add_argument("--secret-env-key", default="")
+    add.add_argument("--cli-target", action="append", default=[])
+    add.add_argument("--header", action="append", default=[])
+
+    list_cmd = profile_sub.add_parser("list", help="List provider profiles")
+    list_cmd.add_argument("--json", action="store_true")
+
+    show = profile_sub.add_parser("show", help="Show one provider profile")
+    show.add_argument("profile_id")
+    show.add_argument("--json", action="store_true")
+
+    test = profile_sub.add_parser("test", help="Run a small live provider probe")
+    test.add_argument("profile_id")
+    test.add_argument("--model", default="")
+    test.add_argument("--json", action="store_true")
+
+    refresh = profile_sub.add_parser("refresh", help="Refresh available models and key quota metadata")
+    refresh.add_argument("profile_id")
+    refresh.add_argument("--json", action="store_true")
+
+    bind = sub.add_parser("bind", help="Bind a provider profile to an agent")
+    bind.add_argument("--profile", dest="profile_id", required=True)
+    bind.add_argument("--agent", required=True)
+    bind.add_argument("--target", default="")
+    bind.add_argument("--default", action="store_true")
+
+    bindings = sub.add_parser("bindings", help="Show current provider bindings")
+    bindings.add_argument("--target", default="")
+    bindings.add_argument("--json", action="store_true")
+
+    invoke = sub.add_parser("invoke", help="Run a non-interactive provider request")
+    invoke.add_argument("--profile", dest="profile_id", default="")
+    invoke.add_argument("--agent", default="")
+    invoke.add_argument("--target", default="")
+    invoke.add_argument("--prompt", required=True)
+    invoke.add_argument("--model", default="")
+    invoke.add_argument("--max-tokens", type=int, default=128)
+    invoke.add_argument("--json", action="store_true")
+
+    status = sub.add_parser("status", help="Show provider status for a target")
+    status.add_argument("--target", required=True)
+    status.add_argument("--json", action="store_true")
+
+    exec_cmd = sub.add_parser("exec", help=argparse.SUPPRESS)
+    exec_cmd.add_argument("--agent", required=True)
+    exec_cmd.add_argument("--cwd", default="")
+    exec_cmd.add_argument("argv", nargs=argparse.REMAINDER)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "profile":
+        if args.profile_command == "add":
+            return cmd_profile_add(args)
+        if args.profile_command == "list":
+            return cmd_profile_list(args)
+        if args.profile_command == "show":
+            return cmd_profile_show(args)
+        if args.profile_command == "test":
+            return cmd_profile_test(args)
+        if args.profile_command == "refresh":
+            return cmd_profile_refresh(args)
+    if args.command == "bind":
+        return cmd_bind(args)
+    if args.command == "bindings":
+        return cmd_bindings(args)
+    if args.command == "invoke":
+        return cmd_invoke(args)
+    if args.command == "status":
+        return cmd_status(args)
+    if args.command == "exec":
+        return cmd_exec(args)
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())