deepparallel 0.4.3__tar.gz → 0.5.0__tar.gz

{deepparallel-0.4.3 → deepparallel-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepparallel
-Version: 0.4.3
+Version: 0.5.0
 Summary: DeepParallel - a multi-model agentic coding CLI with cross-model Guardian review, served via Crowe Logic.
 Author-email: Michael Crowe <michael@crowelogic.com>
 License: Apache-2.0

{deepparallel-0.4.3 → deepparallel-0.5.0}/deepparallel/__init__.py

@@ -1,3 +1,3 @@
 """DeepParallel CLI package."""
 
-__version__ = "0.4.3"
+__version__ = "0.5.0"

{deepparallel-0.4.3 → deepparallel-0.5.0}/deepparallel/backend.py

@@ -16,9 +16,14 @@ from urllib.parse import urlparse
 
 import httpx
 
+from . import crowe_id
+
 Chunk = tuple[str, str]  # (channel, text)
 
 _STREAM_TIMEOUT = httpx.Timeout(120.0, connect=10.0)
+# Modal scale-to-zero cold start can take 2-3 min before the first byte, so the
+# read timeout must be generous; connect stays short.
+_MODAL_TIMEOUT = httpx.Timeout(600.0, connect=15.0)
 _CHECK_TIMEOUT = 4.0
 
 
@@ -210,17 +215,24 @@ class AzureBackend:
 class FoundryBackend:
     label = "Foundry control plane"
 
-    def __init__(self, base_url: str, api_key: str, model: str):
+    def __init__(self, base_url: str, api_key: str, model: str, token_provider=None):
         self._base_url = (base_url or "").rstrip("/")
         self._api_key = api_key or ""
         self._model = model
+        # Optional callable returning a fresh bearer (e.g. a Crowe ID
+        # client_credentials token). When set it takes precedence over the static
+        # api_key, so the gateway sees a sovereign agent identity per request.
+        self._token_provider = token_provider
 
     @property
     def _url(self) -> str:
         return f"{self._base_url}/v1/chat/completions"
 
+    def _bearer(self) -> str:
+        return self._token_provider() if self._token_provider else self._api_key
+
     def check(self) -> tuple[bool, str]:
-        if not self._base_url or not self._api_key:
+        if not self._base_url or not (self._api_key or self._token_provider):
             return False, "Foundry base URL or API key not configured."
         try:
             httpx.get(_host(self._base_url), timeout=_CHECK_TIMEOUT)
@@ -237,7 +249,7 @@ class FoundryBackend:
             "max_tokens": max_tokens,
         }
         headers = {
-            "authorization": f"Bearer {self._api_key}",
+            "authorization": f"Bearer {self._bearer()}",
             "content-type": "application/json",
         }
         with httpx.stream(
@@ -257,7 +269,7 @@ class FoundryBackend:
         if tools:
             payload["tools"] = tools
         headers = {
-            "authorization": f"Bearer {self._api_key}",
+            "authorization": f"Bearer {self._bearer()}",
             "content-type": "application/json",
         }
         r = httpx.post(self._url, json=payload, headers=headers, timeout=_STREAM_TIMEOUT)
@@ -275,7 +287,7 @@ class FoundryBackend:
         if tools:
             payload["tools"] = tools
         headers = {
-            "authorization": f"Bearer {self._api_key}",
+            "authorization": f"Bearer {self._bearer()}",
             "content-type": "application/json",
         }
         with httpx.stream(
@@ -285,8 +297,208 @@ class FoundryBackend:
             return (yield from parse_sse_stream(r.iter_lines()))
 
 
+class PaymentRequired(Exception):
+    """The agent's wallet can't cover the call — the x402 rail returned HTTP 402.
+
+    Carries the parsed x402 envelope so callers can see the price + accepted schemes
+    and decide how to fund (top-up) or pay (X-PAYMENT)."""
+
+    def __init__(self, envelope: dict):
+        self.envelope = envelope or {}
+        accepts = self.envelope.get("accepts", [])
+        price = accepts[0].get("maxAmountRequired", "?") if accepts else "?"
+        schemes = ", ".join(a.get("scheme", "") for a in accepts) or "?"
+        super().__init__(
+            f"payment required: {price} micro-USD via [{schemes}] — fund the agent wallet"
+        )
+
+
+class CroweGatewayBackend:
+    """Foundry gateway PAID agent rail (/api/agent/v1/chat by default), Crowe ID auth.
+
+    Targets the x402 agent endpoint that debits the agent's wallet per call (override
+    with CROWE_AGENT_RESOURCE). Native GatewayResponse shape, not the OpenAI-compat
+    /v1 path (which 404s there); non-streaming with no server-side tool-calls, so we
+    adapt it to DeepParallel's streaming seam by yielding the full completion as a
+    single content chunk. The bearer is a Crowe ID client_credentials token from
+    ``token_provider`` (the agent's sovereign identity).
+    """
+
+    label = "Crowe ID agent (Foundry gateway)"
+
+    def __init__(self, base_url: str, model: str, token_provider=None):
+        self._base_url = (base_url or "").rstrip("/")
+        self._model = model
+        self._token_provider = token_provider
+
+    @property
+    def _url(self) -> str:
+        # The PAID x402 agent rail (debits the agent's wallet). Overridable via
+        # CROWE_AGENT_RESOURCE for the legacy non-paid /api/gateway/chat path.
+        import os
+
+        resource = os.environ.get("CROWE_AGENT_RESOURCE", "/api/agent/v1/chat")
+        return f"{self._base_url}{resource}"
+
+    def _bearer(self) -> str:
+        return self._token_provider() if self._token_provider else ""
+
+    def _headers(self) -> dict:
+        return {
+            "authorization": f"Bearer {self._bearer()}",
+            "content-type": "application/json",
+        }
+
+    def check(self) -> tuple[bool, str]:
+        if not self._base_url or not self._token_provider:
+            return False, "Crowe gateway URL or Crowe ID credentials not configured."
+        try:
+            httpx.get(_host(self._base_url), timeout=_CHECK_TIMEOUT)
+        except Exception as e:  # noqa: BLE001 - reachability probe
+            return False, f"Crowe gateway unreachable ({e.__class__.__name__})"
+        return True, f"Crowe ID @ {_host(self._base_url)}"
+
+    def _complete(self, messages, temperature, max_tokens) -> str:
+        payload = {
+            "model": self._model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        r = httpx.post(self._url, json=payload, headers=self._headers(), timeout=_STREAM_TIMEOUT)
+        if r.status_code == 402:
+            # x402 payment-required: surface the machine-readable envelope as an
+            # actionable error (price + schemes) rather than a raw HTTP error.
+            try:
+                envelope = r.json()
+            except Exception:  # noqa: BLE001 - tolerate a non-JSON 402 body
+                envelope = {}
+            raise PaymentRequired(envelope)
+        r.raise_for_status()
+        return r.json().get("content", "")
+
+    def stream_chat(self, messages, temperature, max_tokens):
+        yield ("content", self._complete(messages, temperature, max_tokens))
+
+    def chat(self, messages, tools, temperature, max_tokens) -> dict:
+        # Native gateway endpoint has no tool-calling; tools are ignored.
+        return {"role": "assistant", "content": self._complete(messages, temperature, max_tokens)}
+
+    def stream_chat_tools(self, messages, tools, temperature, max_tokens):
+        # No server-side tool-calls; yields content and returns the final message
+        # (matches the FoundryBackend generator-return contract used by the agent loop).
+        content = self._complete(messages, temperature, max_tokens)
+        yield ("content", content)
+        return {"role": "assistant", "content": content}
+
+
+class ModalBackend:
+    """Gemma 4 Mycelium served on a Modal scale-to-zero GPU (the free base tier).
+
+    OpenAI-compatible /v1/chat/completions, but the Modal web endpoint requires
+    proxy-auth headers (Modal-Key / Modal-Secret) on every request — which is why
+    the gateway, not OWUI, must own this connection."""
+
+    label = "Modal (Mycelium)"
+
+    def __init__(self, endpoint: str, key: str, secret: str, model: str):
+        self._base_url = (endpoint or "").rstrip("/")
+        self._key = key or ""
+        self._secret = secret or ""
+        self._model = model
+
+    @property
+    def _url(self) -> str:
+        return f"{self._base_url}/v1/chat/completions"
+
+    def _headers(self) -> dict:
+        return {
+            "Modal-Key": self._key,
+            "Modal-Secret": self._secret,
+            "content-type": "application/json",
+        }
+
+    def check(self) -> tuple[bool, str]:
+        if not self._base_url or not self._key or not self._secret:
+            return False, "Modal Mycelium endpoint or proxy-auth token not configured."
+        try:
+            httpx.get(_host(self._base_url), timeout=_CHECK_TIMEOUT)
+        except Exception as e:  # noqa: BLE001 - reachability probe
+            return False, f"Modal endpoint unreachable ({e.__class__.__name__})"
+        return True, f"Modal @ {_host(self._base_url)}"
+
+    def stream_chat(self, messages, temperature, max_tokens):
+        payload = {
+            "model": self._model,
+            "messages": messages,
+            "stream": True,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        with httpx.stream(
+            "POST", self._url, json=payload, headers=self._headers(), timeout=_MODAL_TIMEOUT
+        ) as r:
+            r.raise_for_status()
+            yield from parse_sse_lines(r.iter_lines())
+
+    def chat(self, messages, tools, temperature, max_tokens) -> dict:
+        payload = {
+            "model": self._model,
+            "messages": messages,
+            "stream": False,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if tools:
+            payload["tools"] = tools
+        r = httpx.post(self._url, json=payload, headers=self._headers(), timeout=_MODAL_TIMEOUT)
+        r.raise_for_status()
+        return _message_from_choice(r.json()["choices"][0])
+
+    def stream_chat_tools(self, messages, tools, temperature, max_tokens):
+        payload = {
+            "model": self._model,
+            "messages": messages,
+            "stream": True,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if tools:
+            payload["tools"] = tools
+        with httpx.stream(
+            "POST", self._url, json=payload, headers=self._headers(), timeout=_MODAL_TIMEOUT
+        ) as r:
+            r.raise_for_status()
+            return (yield from parse_sse_stream(r.iter_lines()))
+
+
+_crowe_providers: dict[tuple, crowe_id.CroweIDTokenProvider] = {}
+
+
+def _crowe_token_provider(settings) -> crowe_id.CroweIDTokenProvider:
+    """One memoized token provider per (issuer, client_id) so fusion's many
+    per-deployment backends share a single cached Crowe ID token."""
+    key = (settings.crowe_id_issuer, settings.crowe_id_client_id)
+    provider = _crowe_providers.get(key)
+    if provider is None:
+        provider = crowe_id.CroweIDTokenProvider(
+            settings.crowe_id_issuer,
+            settings.crowe_id_client_id or "",
+            settings.crowe_id_client_secret or "",
+            audience=settings.crowe_id_audience,
+        )
+        _crowe_providers[key] = provider
+    return provider
+
+
 def resolve_backend(settings) -> Backend:
     """Factory keyed on settings.backend."""
+    if settings.backend == "crowe":
+        return CroweGatewayBackend(
+            settings.gateway_url or "",
+            settings.foundry_model,
+            token_provider=_crowe_token_provider(settings),
+        )
     if settings.backend == "foundry":
         return FoundryBackend(
             settings.foundry_base_url or "",
@@ -305,7 +517,22 @@ def backend_for_deployment(settings, deployment: str) -> Backend:
     """Build a backend targeting a specific deployment/model (for fusion).
 
     Uses the same transport as the active backend, just a different model id.
+    The Modal-served Mycelium model is the exception: it routes to its own
+    endpoint with proxy-auth headers, regardless of the active backend.
     """
+    if settings.mycelium_endpoint and deployment == settings.mycelium_model:
+        return ModalBackend(
+            settings.mycelium_endpoint,
+            settings.mycelium_key or "",
+            settings.mycelium_secret or "",
+            deployment,
+        )
+    if settings.backend == "crowe":
+        return CroweGatewayBackend(
+            settings.gateway_url or "",
+            deployment,
+            token_provider=_crowe_token_provider(settings),
+        )
     if settings.backend == "foundry":
         return FoundryBackend(
             settings.foundry_base_url or "", settings.foundry_api_key or "", deployment

{deepparallel-0.4.3 → deepparallel-0.5.0}/deepparallel/branding.py

@@ -111,34 +111,50 @@ class ThinkingSpinner:
         self,
         label: str = "thinking",
         *,
-        lanes: int = 5,
+        lanes: int = 20,
+        rows: int = 3,
         speed: float = 0.45,
-        spread: float = 0.7,
+        spread: float = 0.45,
+        row_phase: float = 1.1,
         hue_speed: float = 0.06,
     ):
         self._label = label
         self._lanes = lanes
+        self._rows = rows  # parallel reasoning streams stacked into a field
         self._speed = speed  # radians advanced per frame (animation tempo)
         self._spread = spread  # phase offset between lanes (crest travel)
+        self._row_phase = row_phase  # phase offset between streams (they desync)
         self._hue_speed = hue_speed  # palette stops advanced per frame (color drift)
         self._tick = 0
 
     def frame(self, tick: int) -> Text:
-        """Build the frame at a given tick (pure; used for rendering + tests)."""
+        """Build the frame at a given tick (pure; used for rendering + tests).
+
+        An amplified multi-row FIELD of parallel reasoning streams: each row is a
+        lane of pulse blocks with a bright crest travelling across it, the rows
+        desynced by `row_phase` so the field shimmers like many chains computing
+        at once. Row 0 carries the ◆ mark + label (so `.plain` starts with ◆)."""
         text = Text()
         crest = _crest_color(tick * self._hue_speed)  # this frame's drifting hue
-        text.append(f"{MARK} ", style=f"bold {crest}")
-        for i in range(self._lanes):
-            level = (math.sin(tick * self._speed - i * self._spread) + 1) / 2  # 0..1
-            # Crest cells take the live hue; mid cells a dimmed blend; troughs go dim.
-            if level > 0.72:
-                style = f"bold {crest}"
-            elif level > 0.4:
-                style = _lerp_hex("#3a4a4a", crest, 0.6)
+        for r in range(self._rows):
+            if r == 0:
+                text.append(f"{MARK} ", style=f"bold {crest}")
             else:
-                style = DIM
-            text.append(_PULSE_BLOCKS[round(level * (len(_PULSE_BLOCKS) - 1))], style=style)
-        text.append(f"  {self._label}…", style=DIM)
+                text.append("\n  ")  # continuation streams indent under the mark
+            for i in range(self._lanes):
+                level = (
+                    math.sin(tick * self._speed - i * self._spread - r * self._row_phase) + 1
+                ) / 2  # 0..1
+                # Crest cells take the live hue; mid cells a dimmed blend; troughs dim.
+                if level > 0.72:
+                    style = f"bold {crest}"
+                elif level > 0.4:
+                    style = _lerp_hex("#3a4a4a", crest, 0.6)
+                else:
+                    style = DIM
+                text.append(_PULSE_BLOCKS[round(level * (len(_PULSE_BLOCKS) - 1))], style=style)
+            if r == 0:
+                text.append(f"  {self._label}…", style=DIM)
         return text
 
     def __rich__(self) -> Text:
@@ -187,7 +203,10 @@ def render_tool_card(
     result: str = "",
     duration_ms: int = 0,
 ) -> None:
-    """Render a tool call as a running line, or a done/failed panel."""
+    """Render a tool call as a running line, a one-line success, or a failure
+    panel. Success stays on a single line so a long agent turn reads as a tight
+    ledger of actions; only failures get a bordered block, so red weight means
+    something went wrong."""
     if status == "running":
         line = Text()
         line.append(f"{ARROW} ", style=DP_ACCENT)
@@ -198,11 +217,20 @@ def render_tool_card(
         console.print(_gutter(line))
         return
 
-    ok = status == "ok"
-    glyph = CHECK if ok else CROSS
-    accent = GREEN_HEX if ok else RED_HEX
+    if status == "ok":
+        line = Text()
+        line.append(f"{CHECK} ", style=GREEN_HEX)
+        line.append(name, style=f"bold {DP_ACCENT}")
+        line.append(f" {DOT} {duration_ms / 1000:.1f}s", style=DIM)
+        if args:
+            line.append(f" {DOT} {preview_tool_args(args)}", style=DIM)
+        if result:
+            line.append(f" {DOT} {preview_tool_args(result, limit=96)}", style=DIM)
+        console.print(_gutter(line))
+        return
+
     header = Text()
-    header.append(f"{glyph} ", style=accent)
+    header.append(f"{CROSS} ", style=RED_HEX)
     header.append(name, style=f"bold {DP_ACCENT}")
     header.append(f"  {DOT} {duration_ms / 1000:.1f}s", style=DIM)
     parts = [header]
@@ -211,7 +239,7 @@ def render_tool_card(
     if result:
         parts.append(Text(preview_tool_args(result, limit=200), style=WHITE_HEX))
     group = Group(*parts) if len(parts) > 1 else header
-    console.print(_gutter(Panel(group, border_style=accent, box=box.ROUNDED)))
+    console.print(_gutter(Panel(group, border_style=RED_HEX, box=box.ROUNDED)))
 
 
 def render_error(console: Console, title: str, detail: str = "") -> None:
@@ -277,6 +305,64 @@ def compact_wordmark() -> str:
     return f"[bold {DP_ACCENT}]{MARK} DeepParallel[/]"
 
 
+def animate_wordmark(console, *, animate: bool = True) -> None:
+    """Animated drop-in reveal of the DEEPPARALLEL block wordmark.
+
+    The rows land top-to-bottom - each landing row flashes bright before settling
+    to cyan - then the whole block shimmers once. Distinct motion from sibling
+    CLIs (vertical drop-in vs. horizontal sweep) while sharing the amplified feel.
+
+    Narrow panes use the compact one-line mark. `animate=False` (tests / non-tty)
+    prints the block statically - same glyphs, no real-time motion.
+    """
+    rows = wordmark_lines()
+    if console.width < wordmark_width():
+        console.print(compact_wordmark(), highlight=False)
+        return
+    if not (animate and getattr(console, "is_terminal", False)):
+        for line in rows:
+            console.print(f"[{DP_ACCENT}]{line}[/]", highlight=False)
+        return
+
+    import time
+
+    from rich.live import Live
+
+    w = wordmark_width()
+    padded = [line.ljust(w) for line in rows]
+    n = len(padded)
+
+    def cascade(landed: int, flash: int | None) -> Text:
+        t = Text()
+        for i in range(landed):
+            style = "bold bright_white" if i == flash else f"bold {DP_ACCENT}"
+            t.append(padded[i], style=style)
+            if i < landed - 1:
+                t.append("\n")
+        return t
+
+    def shine(band: int) -> Text:
+        t = Text()
+        for i, line in enumerate(padded):
+            for ci, ch in enumerate(line):
+                style = "bold bright_white" if band <= ci < band + 6 else f"bold {DP_ACCENT}"
+                t.append(ch, style=style)
+            if i < n - 1:
+                t.append("\n")
+        return t
+
+    with Live(console=console, transient=False, refresh_per_second=120) as live:
+        for k in range(1, n + 1):  # cascade: each row drops in and flashes white
+            live.update(cascade(k, k - 1))
+            time.sleep(0.09)
+            live.update(cascade(k, None))  # settle that row to cyan
+            time.sleep(0.05)
+        for band in range(-6, w + 7, 3):  # bright shine sweeps across the block
+            live.update(shine(band))
+            time.sleep(0.012)
+        live.update(Text("\n".join(rows), style=f"bold {DP_ACCENT}"))  # final settle
+
+
 def status_text(
     *, version: str, tool_count: int, fusion_modes: tuple[str, ...], backend_label: str
 ):
@@ -287,6 +373,7 @@ def status_text(
     body.append(f"  {DOT} v{version}  {DOT} ", style=DIM)
     body.append("served via Crowe Logic\n", style=f"bold {CROWE_ACCENT}")
     body.append(f"{tool_count} tools", style=WHITE_HEX)
+    body.append(f" {DOT} 5,800+ MCP servers", style=DIM)
     body.append(f"  {DOT} fusion: {fusion}\n", style=DIM)
     body.append("Backend: ", style=DIM)
     body.append(f"{backend_label}\n\n", style="white")

{deepparallel-0.4.3 → deepparallel-0.5.0}/deepparallel/config.py

@@ -39,6 +39,19 @@ class Settings:
     judge_deployment: str
     guardian_enabled: bool
     guardian_deployment: str
+    # Modal-served Gemma 4 Mycelium (free base tier). Inert until the endpoint +
+    # proxy-auth token are set; routes through ModalBackend when configured.
+    mycelium_endpoint: str | None = None
+    mycelium_key: str | None = None
+    mycelium_secret: str | None = None
+    mycelium_model: str = "Mcrowe1210/gemma-4-mycelium-e4b"
+    # Crowe ID agent identity (backend="crowe"): route through the Foundry gateway
+    # authenticated by a client_credentials token instead of a raw provider key.
+    gateway_url: str | None = None
+    crowe_id_issuer: str = "https://id.crowelogic.com/realms/crowe"
+    crowe_id_client_id: str | None = None
+    crowe_id_client_secret: str | None = None
+    crowe_id_audience: str | None = None
 
 
 @dataclass(frozen=True)
@@ -89,7 +102,7 @@ def _int_env(name: str, default: int) -> int:
 
 def resolve_settings() -> Settings:
     backend = os.environ.get("DEEPPARALLEL_BACKEND", "azure").strip().lower()
-    if backend not in {"azure", "foundry"}:
+    if backend not in {"azure", "foundry", "crowe"}:
         backend = "azure"
     return Settings(
         backend=backend,
@@ -122,6 +135,20 @@ def resolve_settings() -> Settings:
         # model spends a small token budget on hidden thinking and returns no
         # verdict). Differs from the primary author model for a real 2nd opinion.
         guardian_deployment=os.environ.get("DEEPPARALLEL_GUARDIAN_DEPLOYMENT", "DeepSeek-V4-Flash"),
+        mycelium_endpoint=os.environ.get("MODAL_MYCELIUM_ENDPOINT"),
+        mycelium_key=os.environ.get("MODAL_MYCELIUM_KEY"),
+        mycelium_secret=os.environ.get("MODAL_MYCELIUM_SECRET"),
+        mycelium_model=os.environ.get(
+            "DEEPPARALLEL_MYCELIUM_MODEL", "Mcrowe1210/gemma-4-mycelium-e4b"
+        ),
+        gateway_url=os.environ.get(
+            "CROWE_LOGIC_GATEWAY_URL",
+            "https://foundry-control-plane-production.up.railway.app",
+        ),
+        crowe_id_issuer=os.environ.get("CROWE_ID_ISSUER", "https://id.crowelogic.com/realms/crowe"),
+        crowe_id_client_id=os.environ.get("CROWE_ID_CLIENT_ID"),
+        crowe_id_client_secret=os.environ.get("CROWE_ID_CLIENT_SECRET"),
+        crowe_id_audience=os.environ.get("CROWE_ID_AUDIENCE"),
     )
 
 
@@ -133,6 +160,13 @@ def missing_required(settings: Settings) -> list[str]:
             missing.append("AZURE_CORE_ENDPOINT")
         if not settings.azure_api_key:
             missing.append("AZURE_CORE_API_KEY")
+    elif settings.backend == "crowe":
+        if not settings.gateway_url:
+            missing.append("CROWE_LOGIC_GATEWAY_URL")
+        if not settings.crowe_id_client_id:
+            missing.append("CROWE_ID_CLIENT_ID")
+        if not settings.crowe_id_client_secret:
+            missing.append("CROWE_ID_CLIENT_SECRET")
     else:
         if not settings.foundry_base_url:
             missing.append("FOUNDRY_BASE_URL")

deepparallel-0.5.0/deepparallel/crowe_id.py

@@ -0,0 +1,75 @@
+"""Crowe ID (Keycloak) OAuth2 client_credentials token provider.
+
+Lets DeepParallel authenticate to the Crowe Logic Foundry gateway with a sovereign
+*agent* identity instead of a raw provider API key: it mints a client_credentials
+access token from Crowe ID, caches it until shortly before expiry, and hands it to
+the Foundry/OpenAI-compat backend as the Bearer token. The only side effect is the
+token POST (and its in-memory cache).
+"""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+
+class CroweIDError(Exception):
+    """A Crowe ID token request failed or returned no usable access token."""
+
+
+class CroweIDTokenProvider:
+    """Mints + caches a client_credentials access token from Crowe ID.
+
+    Call ``token()`` (or the instance directly) to get a currently-valid bearer.
+    The token is refreshed automatically once it is within ``leeway`` seconds of
+    expiry so a long CLI session never hands the gateway a stale token.
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        client_id: str,
+        client_secret: str,
+        audience: str | None = None,
+        *,
+        leeway: int = 30,
+        timeout: int = 15,
+    ):
+        self._token_url = f"{issuer.rstrip('/')}/protocol/openid-connect/token"
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._audience = audience
+        self._leeway = leeway
+        self._timeout = timeout
+        self._cached: tuple[str, float] | None = None  # (token, expires_at_monotonic)
+
+    def token(self) -> str:
+        now = time.monotonic()
+        if self._cached and now < self._cached[1]:
+            return self._cached[0]
+        tok, ttl = self._fetch()
+        self._cached = (tok, now + max(0, ttl - self._leeway))
+        return tok
+
+    def __call__(self) -> str:
+        return self.token()
+
+    def _fetch(self) -> tuple[str, int]:
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        if self._audience:
+            data["audience"] = self._audience
+        try:
+            resp = httpx.post(self._token_url, data=data, timeout=self._timeout)
+            resp.raise_for_status()
+            body = resp.json()
+        except Exception as exc:  # noqa: BLE001 - surface any transport/HTTP failure uniformly
+            raise CroweIDError(f"Crowe ID token request failed: {exc}")
+        tok = body.get("access_token")
+        if not tok:
+            raise CroweIDError("Crowe ID response missing access_token")
+        return tok, int(body.get("expires_in", 300))