@maudecode/talaria-web 1.18.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/stt.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 
 import base64
 import logging
-import os
+import secrets
 import tempfile
+import threading
 from pathlib import Path
 
 from ..errors import InvalidParams, RpcError
@@ -16,85 +17,141 @@ log = logging.getLogger("talaria_sidecar.stt")
 
 
 def capability() -> tuple[bool, str]:
+    """The provider the Agent's own resolver would transcribe with, so the client never disagrees with ``stt.transcribe``.
+
+    ``_get_provider`` passes an unknown explicit name through, so availability takes the Agent's
+    ``check_voice_requirements`` bar: a built-in, a ``stt.providers.<name>`` command, or an available plugin."""
     try:
-        import tools.transcription_tools as stt
-    except ImportError:
-        return False, "none"
-    try:
-        load_cfg = getattr(stt, "_load_stt_config", None)
-        stt_config = load_cfg() if callable(load_cfg) else {}
-        cfg = stt_config if isinstance(stt_config, dict) else {}
-        is_enabled = getattr(stt, "is_stt_enabled", None)
-        if callable(is_enabled) and not is_enabled(stt_config):
+        from tools.transcription_tools import (
+            BUILTIN_STT_PROVIDERS, _get_provider, _load_stt_config, _resolve_command_stt_provider_config)
+        from tools.voice_mode import _check_plugin_stt_provider
+
+        stt_config = _load_stt_config()
+        provider = str(_get_provider(stt_config) or "none")
+        if provider == "none":
             return False, "none"
-        has_flags = any(hasattr(stt, n) for n in ("_HAS_FASTER_WHISPER", "_HAS_OPENAI", "_HAS_MISTRAL"))
-        get_provider = getattr(stt, "_get_provider", None)
-        if callable(get_provider) and not has_flags:
-            provider = str(get_provider(stt_config) or "none")
-            return provider not in ("", "none"), provider or "none"
-
-        def env(name):
-            getter = getattr(stt, "get_env_value", None)
-            try:
-                if callable(getter):
-                    return str(getter(name) or "").strip()
-            except Exception:  # noqa: BLE001
-                return ""
-            return os.getenv(name, "").strip()
-
-        def helper(name) -> bool:
-            fn = getattr(stt, name, None)
-            try:
-                return bool(fn()) if callable(fn) else False
-            except Exception:  # noqa: BLE001
-                return False
-
-        def local_command_available() -> bool:
-            return helper("_has_local_command") and helper("_find_ffmpeg_binary")
-
-        def command_provider_available(provider) -> bool:
-            resolver = getattr(stt, "_resolve_command_stt_provider_config", None)
-            try:
-                return callable(resolver) and resolver(provider, cfg) is not None
-            except Exception:  # noqa: BLE001
-                return False
-
-        def resolve(provider):
-            if provider == "local":
-                return "local" if getattr(stt, "_HAS_FASTER_WHISPER", False) else "local_command" if local_command_available() else "none"
-            if provider == "local_command":
-                return "local_command" if local_command_available() else "local" if getattr(stt, "_HAS_FASTER_WHISPER", False) else "none"
-            if provider == "groq":
-                return "groq" if getattr(stt, "_HAS_OPENAI", False) and env("GROQ_API_KEY") else "none"
-            if provider == "openai":
-                return "openai" if getattr(stt, "_HAS_OPENAI", False) and helper("_has_openai_audio_backend") else "none"
-            if provider == "mistral":
-                return "mistral" if getattr(stt, "_HAS_MISTRAL", False) and env("MISTRAL_API_KEY") else "none"
-            if provider == "xai":
-                try:
-                    from tools.xai_http import resolve_xai_http_credentials
-
-                    return "xai" if resolve_xai_http_credentials().get("api_key") else "none"
-                except Exception:  # noqa: BLE001
-                    return "none"
-            if provider == "elevenlabs":
-                return "elevenlabs" if env("ELEVENLABS_API_KEY") else "none"
-            return provider if command_provider_available(provider) else "none"
-
-        if "provider" in cfg:
-            configured = str(cfg.get("provider") or "local")
-            provider = resolve(configured)
-            return provider != "none", provider if provider != "none" else configured
-        for candidate in ("local", "local_command", "groq", "openai", "mistral", "xai", "elevenlabs"):
-            provider = resolve(candidate)
-            if provider != "none":
-                return True, provider
-        return False, "none"
-    except Exception:  # noqa: BLE001
+        available = (provider in BUILTIN_STT_PROVIDERS
+                     or _resolve_command_stt_provider_config(provider, stt_config) is not None
+                     or _check_plugin_stt_provider(provider))
+    except Exception:  # noqa: BLE001 - an Agent without STT, or a broken STT config
         return False, "none"
+    return bool(available), provider
+
+
+def streaming_available() -> bool:
+    """``stt.streaming`` is on and the provider has a live wire with credentials (False on an Agent without one)."""
+    try:
+        from tools.transcription_streaming import streaming_available as agent_streaming_available
 
+        return bool(agent_streaming_available())
+    except Exception:  # noqa: BLE001 - an Agent without live STT, or a broken STT config
+        return False
 
-def transcribe(audio_b64: str, suffix: str) -> str:
+
+def dictation(transcript: str) -> dict:
+    """The transcript, emptied with ``filtered`` when it is a phrase Whisper invents on silent audio (TAL-917).
+
+    The Agent's ``transcribe_recording`` filter, without its voice-mode tagging. An Agent without it keeps the text."""
+    transcript = transcript.strip()
+    try:
+        from tools.voice_mode_transcript import is_whisper_hallucination
+    except ImportError:
+        return {"transcript": transcript, "filtered": False}
+    if transcript and is_whisper_hallucination(transcript):
+        return {"transcript": "", "filtered": True}
+    return {"transcript": transcript, "filtered": False}
+
+
+def _agent_warmer():
+    """The Agent's ``warm_stt_provider``, or None on an Agent without ``tools.stt_lease``."""
+    try:
+        from tools.stt_lease import warm_stt_provider
+    except ImportError:
+        return None
+    return warm_stt_provider
+
+
+def warm() -> dict:
+    """Pre-load the profile's local engine so the next ``stt.transcribe`` starts hot (TAL-916); a no-op for remote providers.
+
+    Blocking: a first use downloads and loads the model. The Agent's warmer never raises."""
+    warmer = _agent_warmer()
+    if warmer is None:
+        return {"provider": capability()[1], "warmed": False, "action": "unsupported"}
+    result = warmer()
+    out = {"provider": str(result.get("provider") or "none"), "warmed": bool(result.get("warmed")), "action": str(result.get("action") or "noop")}
+    if result.get("error"):
+        out["error"] = str(result["error"])
+    return out
+
+
+# Open live sessions by stream id: the ``stt.stream`` call owns each entry and removes it on every exit.
+_STREAMS: dict[str, tuple[object, threading.Event]] = {}
+_STREAMS_LOCK = threading.Lock()
+
+
+def open_stream(ctx: CallContext):
+    """The profile's live session relaying partials as ``partial`` frames, or None (run under the profile's home).
+
+    ``capability`` first, so a plugin provider is discovered before the session opens."""
+    available, _ = capability()
+    if not (available and streaming_available()):
+        return None
+    from tools.transcription_streaming import open_streaming_session
+
+    return open_streaming_session(on_partial=lambda text: ctx.emit("partial", {"text": text}))
+
+
+def run_stream(ctx: CallContext, session, sample_rate: int) -> dict:
+    """Announce the session's id, wait for ``stt.stream_audio`` to end the audio, and return its final transcript.
+
+    The session's worker keeps the opener's profile context; every exit other than a final cancels it."""
+    ended = threading.Event()
+    stream_id = secrets.token_urlsafe(16)
+    with _STREAMS_LOCK:
+        _STREAMS[stream_id] = (session, ended)
+    try:
+        session.set_input_rate(sample_rate)
+        ctx.emit("ready", {"stream_id": stream_id})
+        while not ended.wait(0.1):
+            ctx.check_cancelled()
+        # Finalize off this thread so a cancel still reaches the session while the provider flushes.
+        finalized: dict = {}
+        finalizer = threading.Thread(target=lambda: finalized.update(result=session.finalize()), name="stt-stream-finalize", daemon=True)
+        finalizer.start()
+        while finalizer.is_alive():
+            finalizer.join(0.1)
+            ctx.check_cancelled()
+        result = finalized.get("result")
+    except BaseException:
+        session.cancel()
+        raise
+    finally:
+        with _STREAMS_LOCK:
+            _STREAMS.pop(stream_id, None)
+    if not isinstance(result, dict) or not result.get("success"):
+        message = str(result.get("error") or "") if isinstance(result, dict) else ""
+        raise RpcError(message or "Live transcription failed", condition="stt_failed")
+    return {**dictation(str(result.get("transcript") or "")), "provider": str(result.get("provider") or "")}
+
+
+def stream_audio(stream_id: str, audio_b64: str, end: bool) -> dict:
+    with _STREAMS_LOCK:
+        entry = _STREAMS.get(stream_id)
+    if entry is None:
+        raise RpcError("Live transcription stream is closed", condition="stt_stream_closed")
+    session, ended = entry
+    if audio_b64:
+        try:
+            session.push_audio(base64.b64decode(audio_b64, validate=True))
+        except ValueError as exc:
+            raise InvalidParams("audio must be base64") from exc
+    if end:
+        ended.set()
+    return {"ok": True}
+
+
+def transcribe(audio_b64: str, suffix: str) -> dict:
     try:
         from tools.transcription_tools import transcribe_audio
     except ImportError as exc:
@@ -115,7 +172,7 @@ def transcribe(audio_b64: str, suffix: str) -> str:
         message = str((result or {}).get("error") or "Transcription failed") if isinstance(result, dict) else "Transcription failed"
         lowered = message.lower()
         raise RpcError(message, condition="stt_unavailable" if "unavailable" in lowered or "not configured" in lowered else "stt_failed")
-    return str(result.get("transcript") or "").strip()
+    return dictation(str(result.get("transcript") or ""))
 
 
 def register(registry) -> None:
@@ -123,9 +180,33 @@ def register(registry) -> None:
     def capability_(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
             available, provider = capability()
-        return {"available": bool(available), "provider": provider}
+            streaming = available and streaming_available()
+        # Only the local engine has anything resident to load; the Agent's warmer no-ops every other provider.
+        warm_supported = bool(available) and provider == "local" and _agent_warmer() is not None
+        return {"available": bool(available), "provider": provider, "streaming": bool(streaming), "warm_supported": warm_supported}
+
+    @registry.method("stt.warm")
+    def warm_(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return warm()
 
     @registry.method("stt.transcribe")
     def transcribe_(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
-            return {"transcript": transcribe(str(params.get("audio_b64") or ""), str(params.get("suffix") or ".webm"))}
+            return transcribe(str(params.get("audio_b64") or ""), str(params.get("suffix") or ".webm"))
+
+    @registry.method("stt.stream")
+    def stream_(ctx: CallContext, params: dict) -> dict:
+        sample_rate = params.get("sample_rate")
+        if not isinstance(sample_rate, int) or not 8000 <= sample_rate <= 48000:
+            raise InvalidParams("sample_rate must be an integer from 8000 to 48000")
+        # Open under the profile's home, then wait outside it: the scope is not held for the whole dictation.
+        with scoped_home(profile_home_param(params)):
+            session = open_stream(ctx)
+        if session is None:
+            raise RpcError("Live transcription is unavailable for the configured provider", condition="stt_stream_unavailable")
+        return run_stream(ctx, session, sample_rate)
+
+    @registry.method("stt.stream_audio")
+    def stream_audio_(ctx: CallContext, params: dict) -> dict:
+        return stream_audio(str(params.get("stream_id") or ""), str(params.get("audio_b64") or ""), bool(params.get("end")))

package/sidecar/talaria_sidecar/methods/text.py

@@ -1,5 +1,5 @@
 """``text.*``: pure helpers from the Agent that the server must match exactly
-(image input routing, portal tags)."""
+(image input routing, portal tags, spoken text)."""
 
 from __future__ import annotations
 
@@ -65,6 +65,15 @@ def portal_tags() -> dict:
     return out
 
 
+def spoken(text: str) -> dict:
+    """TAL-906: the Agent's read-aloud script for ``text``; the text as written on an Agent without the normalizer."""
+    try:
+        from tools.tts_text_normalize import prepare_spoken_text
+    except Exception:  # noqa: BLE001
+        return {"spoken_text": text}
+    return {"spoken_text": prepare_spoken_text(text)}
+
+
 def register(registry) -> None:
     @registry.method("text.image_mode")
     def image_mode_(ctx: CallContext, params: dict) -> dict:
@@ -80,3 +89,7 @@ def register(registry) -> None:
     def tags(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
             return portal_tags()
+
+    @registry.method("text.spoken")
+    def spoken_(ctx: CallContext, params: dict) -> dict:
+        return spoken(str(params.get("text") or ""))

package/sidecar/talaria_sidecar/methods/toolsets.py

@@ -0,0 +1,51 @@
+"""Profile toolset policy and catalog. All callers run under ``scoped_home``."""
+
+from __future__ import annotations
+
+from ..home import profile_home_param, scoped_home
+
+
+def disabled_toolsets(cfg: dict | None = None) -> list[str]:
+    from agent.skill_utils import parse_config_string_list
+    from hermes_cli.config import load_config
+
+    section = ((load_config() or {}) if cfg is None else cfg).get('agent') or {}
+    return [name.strip() for name in parse_config_string_list(section.get('disabled_toolsets')) if name.strip()]
+
+
+def catalog(override) -> dict:
+    from hermes_cli.plugins import discover_plugins
+    from model_tools import get_tool_definitions
+    import toolsets
+    from toolsets import get_all_toolsets, resolve_toolset
+    from .chat import _profile_toolsets
+    from .commands import discover_profile_mcp_tools
+
+    discover_plugins()
+    discover_profile_mcp_tools()
+    definitions = get_all_toolsets()
+    disabled = disabled_toolsets()
+    platform_policy = getattr(toolsets, "session_disabled_toolsets", None)
+    effective_disabled = platform_policy(disabled, "webui") if platform_policy else disabled
+    selected = _profile_toolsets() if override is None else list(dict.fromkeys(override))
+    # Resolve once through the same Agent filter used at execution, before deferred-tool assembly.
+    tools = {item['function']['name'] for item in get_tool_definitions(
+        enabled_toolsets=list(definitions), disabled_toolsets=effective_disabled,
+        quiet_mode=True, skip_tool_search_assembly=True,
+    )}
+    rows = []
+    for name in sorted(set(definitions) | set(selected)):
+        available = name in definitions and name not in disabled and bool(set(resolve_toolset(name)) & tools)
+        rows.append({
+            'name': name, 'description': str(definitions.get(name, {}).get('description') or ''),
+            'available': available, 'selected': name in selected,
+            'unavailable_reason': None if available else 'disabled' if name in disabled else 'unavailable',
+        })
+    return {'toolsets': rows, 'selected_toolsets': selected, 'using_defaults': override is None}
+
+
+def register(registry) -> None:
+    @registry.method('toolsets.catalog')
+    def catalog_(ctx, params):
+        with scoped_home(profile_home_param(params)):
+            return catalog(params.get('enabled_toolsets'))

package/sidecar/talaria_sidecar/methods/usage.py

@@ -4,9 +4,14 @@ state, and the key-based balance endpoints (TAL-548). Pool keys never leave the
 from __future__ import annotations
 
 import dataclasses
+import functools
+import hashlib
+import hmac
+import inspect
 import json
 import logging
 import math
+import secrets
 import time
 import urllib.error
 import urllib.request
@@ -18,6 +23,7 @@ from ..home import profile_home_param, scoped_home
 from ..rpc import CallContext
 
 log = logging.getLogger("talaria_sidecar.usage")
+_KEY_REVISION_SALT = secrets.token_bytes(32)
 
 
 def _plain(value: Any) -> Any:
@@ -102,11 +108,36 @@ def _label(entry, index: int) -> str:
     return label[:61].rstrip() + "..." if len(label) > 64 else label
 
 
+def _usable_key(value: Any) -> str:
+    key = str(value or "").strip()
+    return "" if key.startswith("op://") else key
+
+
+def _configured_key(api_key: str | None, env_vars: list[str] | None) -> str:
+    """Called only inside scoped_home: prefer an explicit key, else let the Agent resolve its secret sources."""
+    if api_key:
+        return _usable_key(api_key)
+    if not env_vars:
+        return ""
+    try:
+        from hermes_cli.config import get_env_value_prefer_dotenv as get_env
+    except ImportError:  # older Agents still resolve through the installed profile secret scope
+        try:
+            from agent.secret_scope import get_secret as get_env
+        except ImportError:
+            return ""
+    for name in env_vars or []:
+        key = _usable_key(get_env(name))
+        if key:
+            return key
+    return ""
+
+
 def pool(provider: str, *, api_key: str | None = None) -> list[dict]:
     """Python `_local_pool_snapshot` rows: one per pool entry with an id, its local status, whether it holds the
-    server-resolved ``api_key``, and no secrets."""
+    profile-resolved configured key, and no secrets."""
     agent_pool, entries = _pool(provider)
-    configured = str(api_key or "").strip()
+    configured = _usable_key(api_key)
     try:
         from agent.credential_pool import _exhausted_until
     except Exception:  # noqa: BLE001 - an Agent without it cannot date an exhausted mark, so the entry reads as available
@@ -134,6 +165,40 @@ def pool(provider: str, *, api_key: str | None = None) -> list[dict]:
     return rows
 
 
+def limits(providers: list[dict]) -> dict[str, dict]:
+    """TAL-807: the Agent's ``CredentialPool.limit_state`` per pooled provider, ISO-dated, as its ``model.options`` attaches
+    ``limit``: ``account`` when every live entry is benched, else ``models`` for the given models no usable entry can serve
+    yet. A provider without a persisted pool, an unreadable pool, or an Agent before v0.21.6 says nothing."""
+    try:
+        from agent.credential_pool import load_pool
+        from hermes_cli.auth import read_credential_pool
+    except Exception as exc:  # noqa: BLE001
+        raise RpcError(f"credential pool unavailable: {exc}", condition="usage_unavailable") from exc
+    try:
+        pooled = {str(slug) for slug, entries in (read_credential_pool() or {}).items() if entries}
+    except Exception:  # noqa: BLE001
+        log.debug("read_credential_pool() failed", exc_info=True)
+        return {}
+    out: dict[str, dict] = {}
+    for row in providers:
+        slug = str(row.get("slug") or "").strip()
+        if slug not in pooled:
+            continue
+        try:
+            limit_state = getattr(load_pool(slug), "limit_state", None)
+            state = limit_state([str(m) for m in row.get("models") or []]) if callable(limit_state) else None
+        except Exception:  # noqa: BLE001 - one unreadable pool must not hide the others
+            log.debug("limit_state(%r) failed", slug, exc_info=True)
+            continue
+        if not state:
+            continue
+        if state.get("scope") == "account":
+            out[slug] = {"scope": "account", "resets_at": _iso(state["resets_at"])}
+        elif state.get("models"):
+            out[slug] = {"scope": "models", "models": {str(m): _iso(at) for m, at in state["models"].items()}}
+    return out
+
+
 _BALANCE_URLS = {
     "openrouter": "https://openrouter.ai/api/v1/key",
     "deepseek": "https://api.deepseek.com/user/balance",
@@ -204,13 +269,15 @@ def _opencode_go(payload: Any) -> dict | None:
 _BALANCE_PARSERS = {"openrouter": _openrouter, "deepseek": _deepseek, "opencode-go": _opencode_go}
 
 
-def balance(provider: str, *, credential_id: str | None, api_key: str | None) -> dict:
-    """One key-based balance read. A pool credential's key resolves here; otherwise the server passes the configured key."""
+def balance(provider: str, *, credential_id: str | None, api_key: str | None, env_vars: list[str] | None = None) -> dict:
+    """One key-based balance read. A pool credential's key resolves here; otherwise resolve the configured key inside the profile scope."""
     result = {"status": "unavailable", "http_status": None, "quota": None, "label": None, "is_available": None, "balances": [], "windows": []}
-    key = str(api_key or "").strip()
+    key = ""
     if credential_id:
         entry = _entry(provider, credential_id)
-        key = _entry_key(entry) if entry is not None else ""
+        key = _usable_key(_entry_key(entry)) if entry is not None else ""
+    else:
+        key = _configured_key(api_key, env_vars)
     if not key:
         return {**result, "status": "no_key"}
     request = urllib.request.Request(_BALANCE_URLS[provider], headers={"Authorization": f"Bearer {key}", "Accept": "application/json", "User-Agent": "Talaria-Web/1.0"})
@@ -232,10 +299,10 @@ _ANTHROPIC_WINDOWS = (("five_hour", "Current session"), ("seven_day", "Current w
 
 
 def _anthropic_usage(token: str):
-    """The Agent's Anthropic account-usage read for one given token. The Agent's fetcher reads only the ambient token, so a
-    pool account would otherwise report the active account's limits."""
-    # ponytail: mirrors agent.account_usage._fetch_anthropic_account_usage on the Agent's own helpers; drop it once that
-    # fetcher honours its api_key argument.
+    """The Agent's Anthropic account-usage read for one given token. An Agent before v0.21.6 reads only the ambient token,
+    so a pool account would otherwise report the active account's limits."""
+    # ponytail: mirrors agent.account_usage._fetch_anthropic_account_usage on the Agent's own helpers; TAL-351 drops it
+    # once v0.21.6 is the oldest supported Agent.
     from agent import account_usage as agent_usage
 
     if not agent_usage._is_oauth_token(token):
@@ -250,7 +317,18 @@ def _anthropic_usage(token: str):
     return agent_usage._snapshot("anthropic", "oauth_usage_api", windows, details)
 
 
+@functools.cache
+def _reads_read_only(fetch) -> bool:
+    """Agent v0.21.6+: ``fetch_account_usage(read_only=, identity_id=)`` reads one pool account without refreshing or
+    rotating its credential, and every fetcher honours the explicit key. TAL-351 drops the check with the mirror."""
+    try:
+        return {"read_only", "identity_id"} <= inspect.signature(fetch).parameters.keys()
+    except (TypeError, ValueError):
+        return False
+
+
 def account(provider: str, *, base_url: str | None, api_key: str | None, credential_id: str | None = None) -> dict | None:
+    entry = None
     if credential_id:
         # One pool account's usage, read with that account's own key.
         entry = _entry(provider, credential_id)
@@ -265,7 +343,12 @@ def account(provider: str, *, base_url: str | None, api_key: str | None, credent
     except Exception as exc:  # noqa: BLE001
         raise RpcError(f"account usage unavailable: {exc}", condition="usage_unavailable") from exc
     try:
-        if credential_id and provider == "anthropic":
+        if entry is not None and _reads_read_only(fetch_account_usage):
+            # A display read never repairs the account: a rejected key reads as unavailable, never as a credential refresh.
+            from agent.account_usage_cache import _identity_id_for
+
+            snapshot = fetch_account_usage(provider, base_url=base_url, api_key=api_key, read_only=True, identity_id=_identity_id_for(provider, entry))
+        elif entry is not None and provider == "anthropic":
             snapshot = _anthropic_usage(api_key)
         else:
             snapshot = fetch_account_usage(provider, base_url=base_url, api_key=api_key)
@@ -301,12 +384,28 @@ def register(registry) -> None:
         if not provider:
             raise InvalidParams("provider is required")
         with scoped_home(profile_home_param(params)):
-            return {"entries": pool(provider, api_key=params.get("api_key"))}
+            key = _configured_key(params.get("api_key"), params.get("env_vars"))
+            return {"entries": pool(provider, api_key=key), "has_api_key": bool(key)}
 
     @registry.method("usage.pool_providers")
     def pool_providers_(ctx: CallContext, params: dict) -> dict:
+        key_envs = params.get("key_envs") or {}
+        if not isinstance(key_envs, dict) or not all(isinstance(pid, str) and isinstance(names, list) and all(isinstance(name, str) for name in names) for pid, names in key_envs.items()):
+            raise InvalidParams("key_envs must map providers to environment variable names")
+        with scoped_home(profile_home_param(params)):
+            keys = {}
+            for provider, names in key_envs.items():
+                key = _configured_key(None, names)
+                keys[provider] = {"present": bool(key), "revision": hmac.new(_KEY_REVISION_SALT, key.encode(), hashlib.sha256).hexdigest() if key else None}
+            return {"providers": pool_providers(), "keys": keys}
+
+    @registry.method("usage.limits")
+    def limits_(ctx: CallContext, params: dict) -> dict:
+        providers = params.get("providers")
+        if not isinstance(providers, list) or not all(isinstance(p, dict) for p in providers):
+            raise InvalidParams("providers must be a list of {slug, models}")
         with scoped_home(profile_home_param(params)):
-            return {"providers": pool_providers()}
+            return {"limits": limits(providers)}
 
     @registry.method("usage.balance")
     def balance_(ctx: CallContext, params: dict) -> dict:
@@ -315,4 +414,4 @@ def register(registry) -> None:
             raise InvalidParams(f"provider must be one of {sorted(_BALANCE_URLS)}")
         credential_id = str(params.get("credential_id") or "").strip() or None
         with scoped_home(profile_home_param(params)):
-            return balance(provider, credential_id=credential_id, api_key=params.get("api_key"))
+            return balance(provider, credential_id=credential_id, api_key=params.get("api_key"), env_vars=params.get("env_vars"))