@maudecode/talaria-web 1.15.0 → 1.16.1

package/sidecar/talaria_sidecar/methods/oauth.py

@@ -0,0 +1,439 @@
+"""``oauth.*``: the Agent's device-code sign-ins for Nous Portal, OpenAI Codex, xAI and MiniMax (TAL-398).
+
+``oauth.start`` asks the provider for a code and answers what the user has to see; a daemon thread then waits for the
+approval and saves the credential with the Agent's own auth-store helpers under the flow's profile home, the steps its
+dashboard and ``hermes auth add`` run. Only the lifecycle is ours: a flow belongs to the home that started it, a cancel
+or an expiry means nothing is saved afterwards, and a new start for the same home and provider supersedes the old one.
+Flows live in this process only.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+log = logging.getLogger("talaria_sidecar.oauth")
+
+_CODEX_ISSUER = "https://auth.openai.com"
+_CODEX_EXPIRES_IN = 15 * 60  # OpenAI's device-code lifetime, as the Agent dashboard uses it
+# An ended flow stays readable this long so the last poll still sees its ending.
+_ENDED_TTL = 10 * 60
+# A pending flow past its code's expiry by this much ends expired even if its provider call has not returned yet.
+_EXPIRY_GRACE = 60
+
+_DENIED = "Sign-in was declined."
+_EXPIRED = "The sign-in code expired before it was approved."
+
+
+class _Stop(Exception):
+    """Raised inside a cancelled flow's provider call so the worker unwinds without saving."""
+
+
+@dataclass
+class Flow:
+    flow_id: str
+    provider: str
+    home: Path
+    expires_at: float
+    interval: int
+    status: str = "pending"
+    error: str | None = None
+    ended_at: float | None = None
+    # The OAuth ``error`` code of the provider's last non-200 answer (``access_denied``, ``expired_token``).
+    oauth_error: str = ""
+    cancelled: threading.Event = field(default_factory=threading.Event)
+    # Serialises the cancel check with the credential save: a cancel cannot land between them.
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def end(self, status: str, error: str | None = None) -> None:
+        self.status, self.error, self.ended_at = status, error, time.time()
+
+    def view(self) -> dict:
+        return {"flow_id": self.flow_id, "provider": self.provider, "status": self.status, "error": self.error}
+
+
+class _Watched:
+    """The HTTP client handed to an Agent poll helper: stops a cancelled flow and records the OAuth error code."""
+
+    def __init__(self, client: Any, flow: Flow):
+        self._client, self._flow = client, flow
+
+    def _guard(self) -> None:
+        if self._flow.cancelled.is_set():
+            raise _Stop()
+
+    def post(self, *args: Any, **kwargs: Any) -> Any:
+        self._guard()
+        response = self._client.post(*args, **kwargs)
+        if response.status_code != 200:
+            try:
+                payload = response.json()
+            except Exception:  # noqa: BLE001 - a non-JSON error carries no OAuth code
+                payload = None
+            if isinstance(payload, dict) and isinstance(payload.get("error"), str):
+                self._flow.oauth_error = payload["error"]
+        return response
+
+    def send(self, *args: Any, **kwargs: Any) -> Any:
+        self._guard()
+        return self._client.send(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+def _first_line(exc: BaseException) -> str:
+    text = (str(exc).strip().splitlines() or [""])[0].strip() or type(exc).__name__
+    return text[:300]
+
+
+def _remaining(flow: Flow) -> int:
+    return max(1, int(flow.expires_at - time.time()))
+
+
+def _now_z() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _client(timeout: float, **kwargs: Any) -> Any:
+    import httpx
+
+    return httpx.Client(timeout=httpx.Timeout(timeout), headers={"Accept": "application/json"}, **kwargs)
+
+
+# ── providers: (begin, wait, save) over the Agent's own steps ──────────
+# begin() -> (display, state) runs under the flow's home; wait(flow, state) -> tokens polls; save(flow, state, tokens)
+# runs under the home with the flow's lock held.
+
+
+def _nous_begin() -> tuple[dict, dict]:
+    from hermes_cli import anon_auth
+    from hermes_cli.auth import PROVIDER_REGISTRY, _request_device_code
+
+    if anon_auth.guest_enabled() and anon_auth.has_guest():
+        # The free tier's sign-in moves its connectors to the account (``anon_auth.run_sign_in``); a plain device-code
+        # sign-in here would orphan them.
+        raise RpcError("This profile uses the Nous free tier. Sign in from Hermes with `hermes portal`.", condition="oauth_unsupported")
+    pconfig = PROVIDER_REGISTRY["nous"]
+    portal = (os.getenv("HERMES_PORTAL_BASE_URL") or os.getenv("NOUS_PORTAL_BASE_URL") or pconfig.portal_base_url).rstrip("/")
+    with _client(15.0) as client:
+        data = _request_device_code(client, portal, pconfig.client_id, pconfig.scope)
+    display = {"user_code": str(data["user_code"]), "verification_url": str(data["verification_uri_complete"]), "expires_in": int(data["expires_in"]), "interval": int(data["interval"])}
+    return display, {"portal": portal, "client_id": pconfig.client_id, "scope": pconfig.scope, "device_code": str(data["device_code"])}
+
+
+def _nous_wait(flow: Flow, state: dict) -> dict:
+    from hermes_cli.auth import _poll_for_token
+
+    with _client(15.0) as client:
+        return _poll_for_token(client=_Watched(client, flow), portal_base_url=state["portal"], client_id=state["client_id"], device_code=state["device_code"],
+                               expires_in=_remaining(flow), poll_interval=flow.interval)
+
+
+def _nous_save(flow: Flow, state: dict, token_data: dict) -> None:
+    from hermes_cli import anon_auth
+    from hermes_cli.auth import persist_nous_credentials, refresh_nous_oauth_from_state
+
+    now = datetime.now(timezone.utc)
+    ttl = int(token_data.get("expires_in") or 0)
+    auth_state = {
+        "portal_base_url": state["portal"], "inference_base_url": token_data.get("inference_base_url"), "client_id": state["client_id"],
+        "scope": token_data.get("scope") or state["scope"], "token_type": token_data.get("token_type", "Bearer"),
+        "access_token": token_data["access_token"], "refresh_token": token_data.get("refresh_token"), "obtained_at": now.isoformat(),
+        "expires_at": datetime.fromtimestamp(now.timestamp() + ttl, tz=timezone.utc).isoformat() if ttl else None, "expires_in": ttl,
+    }
+    full_state = refresh_nous_oauth_from_state(auth_state, timeout_seconds=15.0, force_refresh=False)
+    persist_nous_credentials(full_state)
+    anon_auth.settle_after_upgrade(full_state)
+
+
+def _codex_begin() -> tuple[dict, dict]:
+    from hermes_cli.auth import CODEX_OAUTH_CLIENT_ID
+    from hermes_cli.auth_codex import _codex_request_device_code
+
+    data = _codex_request_device_code(_CODEX_ISSUER, CODEX_OAUTH_CLIENT_ID)
+    display = {"user_code": str(data["user_code"]), "verification_url": f"{_CODEX_ISSUER}/codex/device", "expires_in": _CODEX_EXPIRES_IN, "interval": int(data["interval"])}
+    return display, {"device_auth_id": str(data["device_auth_id"]), "user_code": str(data["user_code"])}
+
+
+def _codex_wait(flow: Flow, state: dict) -> dict:
+    """The Agent's Codex poll (``auth_codex._codex_poll_authorization_code``) cannot be stopped, so its loop runs here:
+    403/404 is still pending, a transport error is retried a few times in a row, and the exchange is the Agent's."""
+    import httpx
+    from hermes_cli.auth import CODEX_OAUTH_CLIENT_ID
+    from hermes_cli.auth_codex import _codex_exchange_authorization_code, _codex_http_client
+
+    payload = {"device_auth_id": state["device_auth_id"], "user_code": state["user_code"]}
+    blips = 0
+    code_resp = None
+    with _codex_http_client(timeout=httpx.Timeout(15.0)) as client:
+        while code_resp is None:
+            if flow.cancelled.wait(flow.interval):
+                raise _Stop()
+            if time.time() >= flow.expires_at:
+                raise TimeoutError(_EXPIRED)
+            try:
+                response = client.post(f"{_CODEX_ISSUER}/api/accounts/deviceauth/token", json=payload, headers={"Content-Type": "application/json"})
+            except httpx.TransportError:
+                blips += 1
+                if blips >= 6:
+                    raise
+                continue
+            blips = 0
+            if response.status_code == 200:
+                code_resp = response.json()
+            elif response.status_code not in (403, 404):
+                raise RuntimeError(f"OpenAI device sign-in returned HTTP {response.status_code}.")
+    if flow.cancelled.is_set():
+        raise _Stop()
+    tokens = _codex_exchange_authorization_code(_CODEX_ISSUER, CODEX_OAUTH_CLIENT_ID, code_resp)
+    return {"access_token": tokens.get("access_token", ""), "refresh_token": tokens.get("refresh_token", "")}
+
+
+def _codex_save(flow: Flow, state: dict, tokens: dict) -> None:
+    from hermes_cli.auth import _save_codex_tokens
+
+    _save_codex_tokens(tokens, _now_z())
+
+
+def _xai_begin() -> tuple[dict, dict]:
+    from hermes_cli.auth import _xai_oauth_discovery, _xai_oauth_request_device_code
+
+    discovery = _xai_oauth_discovery(20.0)
+    with _client(20.0) as client:
+        data = _xai_oauth_request_device_code(client)
+    display = {"user_code": str(data["user_code"]), "verification_url": str(data.get("verification_uri_complete") or data["verification_uri"]),
+               "expires_in": int(data["expires_in"]), "interval": int(data["interval"])}
+    return display, {"discovery": discovery, "device_code": str(data["device_code"])}
+
+
+def _xai_wait(flow: Flow, state: dict) -> dict:
+    from hermes_cli.auth import _xai_oauth_poll_device_token
+
+    with _client(20.0) as client:
+        data = _xai_oauth_poll_device_token(_Watched(client, flow), token_endpoint=state["discovery"]["token_endpoint"], device_code=state["device_code"],
+                                            expires_in=_remaining(flow), poll_interval=flow.interval)
+    return {
+        "access_token": str(data.get("access_token", "") or "").strip(), "refresh_token": str(data.get("refresh_token", "") or "").strip(),
+        "id_token": str(data.get("id_token", "") or "").strip(), "expires_in": data.get("expires_in"),
+        "token_type": str(data.get("token_type") or "Bearer").strip() or "Bearer",
+    }
+
+
+def _xai_save(flow: Flow, state: dict, tokens: dict) -> None:
+    from hermes_cli.auth import _save_xai_oauth_tokens, mark_provider_active_if_unset, unsuppress_credential_source
+
+    # As the Agent dashboard does: persist without taking over an active chat provider, become active only when none
+    # is, and re-enable the device-code source an earlier removal suppressed.
+    _save_xai_oauth_tokens(tokens, discovery=state["discovery"], auth_mode="oauth_device_code", set_active=False, last_refresh=_now_z())
+    mark_provider_active_if_unset("xai-oauth")
+    unsuppress_credential_source("xai-oauth", "device_code")
+
+
+def _minimax_begin() -> tuple[dict, dict]:
+    from hermes_cli.auth import MINIMAX_OAUTH_CLIENT_ID, MINIMAX_OAUTH_GLOBAL_BASE, _minimax_pkce_pair, _minimax_request_user_code
+
+    verifier, challenge, csrf_state = _minimax_pkce_pair()
+    portal = (os.getenv("MINIMAX_PORTAL_BASE_URL") or MINIMAX_OAUTH_GLOBAL_BASE).rstrip("/")
+    with _client(15.0, follow_redirects=True) as client:
+        data = _minimax_request_user_code(client, portal_base_url=portal, client_id=MINIMAX_OAUTH_CLIENT_ID, code_challenge=challenge, state=csrf_state)
+    interval_ms = int(data["interval"]) if data.get("interval") is not None else None
+    # ``expired_in`` is a unix-ms deadline or a TTL in seconds (the Agent's own heuristic).
+    expired_in = int(data["expired_in"])
+    expires_in = max(0, int(expired_in / 1000.0 - time.time())) if expired_in > 1_000_000_000_000 else expired_in
+    display = {"user_code": str(data["user_code"]), "verification_url": str(data["verification_uri"]), "expires_in": expires_in, "interval": max(2, (interval_ms or 2000) // 1000)}
+    return display, {"portal": portal, "client_id": MINIMAX_OAUTH_CLIENT_ID, "verifier": verifier, "user_code": str(data["user_code"]), "expired_in": expired_in, "interval_ms": interval_ms}
+
+
+def _minimax_wait(flow: Flow, state: dict) -> dict:
+    from hermes_cli.auth import _minimax_poll_token
+
+    with _client(15.0, follow_redirects=True) as client:
+        return _minimax_poll_token(_Watched(client, flow), portal_base_url=state["portal"], client_id=state["client_id"], user_code=state["user_code"],
+                                   code_verifier=state["verifier"], expired_in=state["expired_in"], interval_ms=state["interval_ms"])
+
+
+def _minimax_save(flow: Flow, state: dict, token_data: dict) -> None:
+    from hermes_cli.auth import MINIMAX_OAUTH_GLOBAL_INFERENCE, MINIMAX_OAUTH_SCOPE, _minimax_resolve_token_expiry_unix, _minimax_save_auth_state
+
+    now = datetime.now(timezone.utc)
+    expires_at = _minimax_resolve_token_expiry_unix(int(token_data["expired_in"]), now=now)
+    _minimax_save_auth_state({
+        "provider": "minimax-oauth", "region": "global", "portal_base_url": state["portal"], "inference_base_url": MINIMAX_OAUTH_GLOBAL_INFERENCE,
+        "client_id": state["client_id"], "scope": MINIMAX_OAUTH_SCOPE, "token_type": token_data.get("token_type", "Bearer"),
+        "access_token": token_data["access_token"], "refresh_token": token_data["refresh_token"], "resource_url": token_data.get("resource_url"),
+        "obtained_at": now.isoformat(), "expires_at": datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(), "expires_in": max(0, int(expires_at - now.timestamp())),
+    })
+
+
+Provider = tuple[Callable[[], tuple[dict, dict]], Callable[[Flow, dict], dict], Callable[[Flow, dict, dict], None]]
+PROVIDERS: dict[str, Provider] = {
+    "nous": (_nous_begin, _nous_wait, _nous_save),
+    "openai-codex": (_codex_begin, _codex_wait, _codex_save),
+    "xai-oauth": (_xai_begin, _xai_wait, _xai_save),
+    "minimax-oauth": (_minimax_begin, _minimax_wait, _minimax_save),
+}
+
+_FLOWS: dict[str, Flow] = {}
+_FLOWS_LOCK = threading.Lock()
+# The newest start per (home, provider): only it may publish a flow, whatever order the provider requests finish in.
+_GENERATIONS: dict[tuple[str, str], int] = {}
+
+
+def _ending(flow: Flow, exc: BaseException) -> tuple[str, str]:
+    """Classify why a provider call ended without tokens: declined, expired, or another failure with its reason."""
+    code = str(getattr(exc, "code", None) or getattr(exc, "oauth_error_code", None) or "")
+    if flow.oauth_error == "access_denied" or code in ("access_denied", "authorization_denied"):
+        return "denied", _DENIED
+    if flow.oauth_error == "expired_token" or code in ("expired_token", "device_code_timeout", "timeout") or isinstance(exc, TimeoutError) or time.time() >= flow.expires_at:
+        return "expired", _EXPIRED
+    return "error", _first_line(exc)
+
+
+def _run(flow: Flow, wait: Callable[[Flow, dict], dict], save: Callable[[Flow, dict, dict], None], state: dict) -> None:
+    try:
+        tokens = wait(flow, state)
+        with flow.lock:
+            if flow.status != "pending":  # cancelled or expired while the provider answered: nothing is saved
+                return
+            with scoped_home(flow.home):
+                save(flow, state, tokens)
+            flow.end("approved")
+        log.info("oauth: %s sign-in approved (flow=%s)", flow.provider, flow.flow_id[:6])
+    except _Stop:
+        pass
+    except Exception as exc:  # noqa: BLE001 - the thread has no caller; the ending is the flow's status
+        with flow.lock:
+            if flow.status == "pending":
+                flow.end(*_ending(flow, exc))
+        log.info("oauth: %s sign-in ended %s (flow=%s)", flow.provider, flow.status, flow.flow_id[:6])
+
+
+def _cancel(flow: Flow) -> None:
+    with flow.lock:
+        if flow.status == "pending":
+            flow.cancelled.set()
+            flow.end("cancelled")
+
+
+def _home_key(home: Path) -> str:
+    try:
+        return str(home.resolve())
+    except OSError:
+        return str(home)
+
+
+def _same_home(left: Path, right: Path) -> bool:
+    try:
+        return left.resolve() == right.resolve()
+    except OSError:
+        return False
+
+
+def _gc(now: float) -> None:
+    with _FLOWS_LOCK:
+        for flow_id, flow in list(_FLOWS.items()):
+            if flow.ended_at is not None and now - flow.ended_at > _ENDED_TTL:
+                del _FLOWS[flow_id]
+
+
+def _pending(home: Path, provider: str) -> list[Flow]:
+    with _FLOWS_LOCK:
+        return [f for f in _FLOWS.values() if f.provider == provider and f.status == "pending" and _same_home(f.home, home)]
+
+
+def start(home: Path, provider: str, *, providers: dict[str, Provider] | None = None) -> dict:
+    steps = (providers or PROVIDERS).get(provider)
+    if steps is None:
+        raise InvalidParams(f"{provider} has no device-code sign-in")
+    begin, wait, save = steps
+    _gc(time.time())
+    key = (_home_key(home), provider)
+    with _FLOWS_LOCK:
+        generation = _GENERATIONS[key] = _GENERATIONS.get(key, 0) + 1
+    # A new start replaces the pending flow for this home and provider before the code request, so an approval of the
+    # old code that lands while the provider answers can no longer save.
+    for old in _pending(home, provider):
+        _cancel(old)
+    try:
+        with scoped_home(home):
+            display, state = begin()
+    except RpcError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        log.debug("oauth: %s start failed", provider, exc_info=True)
+        raise RpcError(_first_line(exc), condition="oauth_failed") from exc
+    if not str(display["verification_url"]).lower().startswith(("https://", "http://")):
+        # The browser opens this link: anything but a web address is refused before a flow exists.
+        raise RpcError("The provider answered an invalid sign-in link.", condition="oauth_failed")
+    flow = Flow(secrets.token_urlsafe(16), provider, home, time.time() + int(display["expires_in"]), max(1, int(display["interval"])))
+    with _FLOWS_LOCK:
+        if _GENERATIONS.get(key) != generation:
+            # A newer start for this home and provider began while this one waited on the provider: it owns the sign-in.
+            raise RpcError("A newer sign-in for this provider replaced this one.", condition="oauth_superseded")
+        superseded = [f for f in _FLOWS.values() if f.provider == provider and f.status == "pending" and _same_home(f.home, home)]
+        _FLOWS[flow.flow_id] = flow
+    for old in superseded:
+        _cancel(old)
+    threading.Thread(target=_run, args=(flow, wait, save, state), daemon=True, name=f"oauth-{flow.flow_id[:6]}").start()
+    return {"flow_id": flow.flow_id, "provider": provider, "status": "pending", **display}
+
+
+def _flow(home: Path, flow_id: str) -> Flow:
+    with _FLOWS_LOCK:
+        flow = _FLOWS.get(flow_id)
+    if flow is None or not _same_home(flow.home, home):
+        raise RpcError("Unknown or expired sign-in.", condition="oauth_flow_not_found")
+    return flow
+
+
+def poll(home: Path, flow_id: str) -> dict:
+    flow = _flow(home, flow_id)
+    if flow.status == "pending" and time.time() > flow.expires_at + _EXPIRY_GRACE:
+        # The provider call outlived its code: end it now, and a late approval can no longer save.
+        with flow.lock:
+            if flow.status == "pending":
+                flow.cancelled.set()
+                flow.end("expired", _EXPIRED)
+    return flow.view()
+
+
+def cancel(home: Path, flow_id: str) -> dict:
+    flow = _flow(home, flow_id)
+    _cancel(flow)
+    return flow.view()
+
+
+def _flow_id(params: dict) -> str:
+    flow_id = str(params.get("flow_id") or "").strip()
+    if not flow_id:
+        raise InvalidParams("flow_id is required")
+    return flow_id
+
+
+def register(reg) -> None:
+    @reg.method("oauth.start")
+    def start_(ctx: CallContext, params: dict) -> dict:
+        provider = str(params.get("provider") or "").strip().lower()
+        if not provider:
+            raise InvalidParams("provider is required")
+        return start(profile_home_param(params), provider)
+
+    @reg.method("oauth.poll", requires_agent=False)
+    def poll_(ctx: CallContext, params: dict) -> dict:
+        return poll(profile_home_param(params), _flow_id(params))
+
+    @reg.method("oauth.cancel", requires_agent=False)
+    def cancel_(ctx: CallContext, params: dict) -> dict:
+        return cancel(profile_home_param(params), _flow_id(params))

package/sidecar/talaria_sidecar/methods/profiles.py

@@ -18,6 +18,7 @@ from pathlib import Path
 from ..errors import InvalidParams, RpcError
 from ..home import profile_home_param
 from ..rpc import CallContext
+from .config import yaml_parser
 
 log = logging.getLogger("talaria_sidecar.profiles")
 _PROFILE_ID_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}")
@@ -34,12 +35,12 @@ _TERMINAL_ENV = {
 
 
 def _yaml_load(path: Path):
-    try:
-        import yaml
-    except Exception:  # noqa: BLE001
+    """A YAML mapping, or None when the file is absent or malformed; a missing parser raises ``yaml_unavailable``."""
+    if not path.exists():
         return None
+    parser = yaml_parser()
     try:
-        data = yaml.safe_load(path.read_text(encoding="utf-8")) if path.exists() else None
+        data = parser.safe_load(path.read_text(encoding="utf-8"))
     except Exception:  # noqa: BLE001
         return None
     return data if isinstance(data, dict) else None

package/sidecar/talaria_sidecar/methods/providers.py

@@ -11,6 +11,9 @@ from __future__ import annotations
 
 import dataclasses
 import logging
+import sys
+import threading
+from pathlib import Path
 from typing import Any
 
 from ..errors import InvalidParams, RpcError
@@ -61,19 +64,176 @@ def auth_status(provider_id: str | None) -> dict:
     return _plain(status) if isinstance(status, dict) else {"logged_in": bool(status)}
 
 
+def _module_dir(module: Any) -> Path | None:
+    try:
+        return Path(module.__file__).resolve().parent
+    except Exception:  # noqa: BLE001 - namespace/builtin modules have no file
+        return None
+
+
+# The Agent's module-name prefix for provider plugins it imports from a ``$HERMES_HOME`` (``providers._import_plugin_dir``).
+_USER_PLUGIN_MODULE = "_hermes_user_provider_"
+_LOAD_LOCK = threading.Lock()
+_LOAD_ATTEMPTED: set[Path] = set()
+
+
+def _user_plugin_profiles() -> dict[int, tuple[Any, Path]]:
+    """Each registered profile a ``$HERMES_HOME`` provider plugin module holds, with that module's directory."""
+    from providers import list_providers
+    from providers.base import ProviderProfile
+
+    registered = {id(p) for p in list_providers()}
+    out: dict[int, tuple[Any, Path]] = {}
+    for name, module in list(sys.modules.items()):
+        directory = _module_dir(module) if module is not None and name.startswith(_USER_PLUGIN_MODULE) else None
+        if directory is None:
+            continue
+        for value in list(vars(module).values()):
+            if isinstance(value, ProviderProfile) and id(value) in registered:
+                out.setdefault(id(value), (value, directory))
+    return out
+
+
+def _load_plugin(root: Path) -> None:
+    """Load the scoped profile's installed plugin that the process-wide discovery (run under the launch profile) skipped.
+
+    Uses the Agent's own loader, as ``hermes plugins dev`` does, once per directory. A plugin never displaces a provider
+    that is already registered, so one profile's plugin cannot change what another profile's provider id runs.
+    """
+    import providers
+
+    with _LOAD_LOCK:
+        if root in _LOAD_ATTEMPTED:
+            return
+        _LOAD_ATTEMPTED.add(root)
+        before = {p.name: p for p in providers.list_providers()}
+        try:
+            providers._import_plugin_dir(root, "user")
+        except Exception:  # noqa: BLE001 - a broken plugin reads as not loaded
+            log.debug("loading provider plugin %s failed", root, exc_info=True)
+            return
+        after = {p.name: p for p in providers.list_providers()}
+        for name, previous in before.items():
+            if after.get(name) is not previous:
+                providers.register_provider(previous)
+
+
+def installed_plugin_profiles() -> list[tuple[str, Any]]:
+    """``(manifest name, profile | None)`` for each enabled model-provider plugin installed in the scoped home.
+
+    Bundled providers are built-ins, not plugins. The Agent keeps one provider registry per process, so a profile
+    belongs to this home only when the plugin module that registered it lives in one of this home's plugin
+    directories; a plugin the launch discovery skipped is loaded here. ``None`` means the plugin could not be loaded:
+    it failed to import, its provider id is taken by another plugin, or another profile's plugin has the same directory
+    name. ponytail: ownership is read from the plugin module's globals, so a plugin that registers an unbound inline
+    profile also reads as not loaded; track registrations in the Agent if one ever does.
+    """
+    try:
+        from hermes_cli.plugins_discovery import _get_disabled_plugins, _get_enabled_plugins, collect_directory_manifests, gate_manifest
+    except Exception as exc:  # noqa: BLE001
+        raise RpcError(f"plugin providers unavailable: {exc}", condition="plugins_unavailable") from exc
+    disabled, enabled = _get_disabled_plugins(), _get_enabled_plugins()
+    roots = {
+        Path(m.path).resolve(): str(m.name)
+        for m in collect_directory_manifests()
+        if m.kind == "model-provider" and m.source == "user" and m.path and gate_manifest(m, disabled, enabled).enabled
+    }
+    if not roots:
+        return []
+
+    def owned() -> dict[Path, list]:
+        found: dict[Path, list] = {root: [] for root in roots}
+        for profile, directory in _user_plugin_profiles().values():
+            root = next((r for r in roots if directory == r or r in directory.parents), None)
+            if root is not None:
+                found[root].append(profile)
+        return found
+
+    found = owned()
+    missing = [root for root, profiles in found.items() if not profiles]
+    if missing:
+        for root in missing:
+            _load_plugin(root)
+        found = owned()
+    return [(name, p) for root, name in roots.items() for p in (found[root] or [None])]
+
+
+def _other_profile_plugin(provider_id: str) -> bool:
+    """Whether ``provider_id`` is a plugin provider that another profile installed (the registry is process-wide)."""
+    from providers import get_provider_profile
+
+    profile = get_provider_profile(provider_id)
+    if profile is None or id(profile) not in _user_plugin_profiles():
+        return False
+    return not any(p is profile for _name, p in installed_plugin_profiles())
+
+
+def _setup_state(profile: Any) -> str:
+    """The Agent's own setup verdict for a plugin provider, without spawning its CLI or reading its credentials."""
+    try:
+        status = auth_status(profile.name)
+    except RpcError:
+        return "unavailable"
+    if status.get("error"):
+        return "unavailable"
+    if profile.auth_type == "external_process":
+        return "ready" if status.get("configured") else "missing_cli"
+    return "ready" if status.get("logged_in") or status.get("configured") else "needs_setup"
+
+
+def plugin_providers() -> list[dict]:
+    """Sanitized rows for this profile's enabled model-provider plugins: identity and setup state, no paths or secrets."""
+    rows = []
+    for manifest_name, profile in installed_plugin_profiles():
+        if profile is None:
+            rows.append({"name": manifest_name, "display_name": manifest_name, "auth_type": "", "setup": "not_loaded"})
+            continue
+        name = str(profile.name).strip().lower()
+        rows.append({"name": name, "display_name": str(profile.display_name or name).strip(), "auth_type": str(profile.auth_type), "setup": _setup_state(profile)})
+    return rows
+
+
+def _plugin_catalog(provider_id: str) -> list[str]:
+    """Discovery for an installed plugin the Agent's catalog has no fetcher for: the profile's own listing, then its fallback.
+
+    API-key plugins already get both from ``provider_model_ids`` with their key, so only keyless auth types list here.
+    """
+    for _name, profile in installed_plugin_profiles():
+        if profile is None or str(profile.name).strip().lower() != provider_id.strip().lower():
+            continue
+        try:
+            live = profile.fetch_models(timeout=8.0) if profile.supports_model_listing and profile.auth_type != "api_key" else None
+        except Exception:  # noqa: BLE001 - a broken plugin answers with its fallback catalog
+            log.debug("fetch_models(%r) failed", provider_id, exc_info=True)
+            live = None
+        return [str(m) for m in (live or profile.fallback_models or ()) if m]
+    return []
+
+
 def model_ids(provider_id: str, *, force_refresh: bool) -> list[str]:
     try:
         from hermes_cli.models import provider_model_ids
     except Exception as exc:  # noqa: BLE001
         raise RpcError(f"model catalog unavailable: {exc}", condition="providers_unavailable") from exc
+    try:
+        if _other_profile_plugin(provider_id):
+            return []
+    except Exception:  # noqa: BLE001 - no readable provider registry means no plugin to keep apart
+        log.debug("plugin ownership check for %r failed", provider_id, exc_info=True)
     try:
         ids = provider_model_ids(provider_id, force_refresh=force_refresh)
     except TypeError:
         ids = provider_model_ids(provider_id)
     except Exception:  # noqa: BLE001
         log.debug("provider_model_ids(%r) failed", provider_id, exc_info=True)
+        ids = []
+    ids = [str(m) for m in (ids or []) if m]
+    if ids:
+        return ids
+    try:
+        return _plugin_catalog(provider_id)
+    except RpcError:
         return []
-    return [str(m) for m in (ids or []) if m]
 
 
 def resolve_runtime(*, requested: str | None, api_key: str | None, base_url: str | None, target_model: str | None) -> dict:

package/sidecar/talaria_sidecar/methods/runtime.py

@@ -7,6 +7,7 @@ import re
 
 from .. import SIDECAR_RPC_VERSION
 from ..errors import InvalidParams, RpcError
+from ..home import edit_launch_env
 from ..rpc import CallContext
 
 
@@ -53,6 +54,7 @@ def register(registry) -> None:
             os.environ.pop(name, None)
         for name, value in to_set.items():
             os.environ[name] = value
+        edit_launch_env(to_set, to_unset)
         # Cached agents bound the credentials they were built with; none of them may outlive a credential change.
         from .chat import evict_all_agents