orchid-cli 1.1.4__tar.gz → 1.2.0__tar.gz

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/AGENTS.md

@@ -17,11 +17,14 @@ orchid-cli/
       token_store.py Secure token persistence (~/.orchid/tokens.json)
       middleware.py   Token refresh + OrchidAuthContext builder
     commands/
+      _session.py    resolve_session(config_path) -> (Orchid, OrchidAuthContext) +
+                     warm_for_user — single chokepoint for bootstrap + auth + MCP warm
       auth.py        login, logout, status subcommands
       chat.py        Full CRUD: create, list, delete, history, send, interactive, rename, share
       config.py      validate command (checks agents.yaml)
-      index.py       seed command (batch-index RAG data)
-      mcp.py         MCP OAuth: authorize, status, revoke per-server tokens
+      index.py       file/dir/text/json-file commands (RAG ingestion)
+      mcp.py         MCP OAuth: status, revoke per-server tokens
+                     (authorize flow runs through the API gateway, not the CLI)
       skill.py       generate command (Claude Code skills from agents.yaml)
   pyproject.toml
 ```
@@ -52,10 +55,12 @@ orchid-cli/
 
 6. **Config resolution:** CLI args > env vars > `orchid.yml` > hardcoded defaults.
 
-7. **OAuth auth is self-contained in `auth/`.** The `auth/` subpackage handles the full OAuth 2.0 Authorization Code + PKCE flow. No OAuth logic in `chat.py`, `bootstrap.py`, or any other module. Chat commands call `get_auth_context(config_path)` which returns either a real OAuth-backed `OrchidAuthContext` or the dev fallback — callers don't know or care which.
+7. **OAuth auth is self-contained in `auth/`.** The `auth/` subpackage handles the full OAuth 2.0 Authorization Code + PKCE flow. No OAuth logic in `chat.py`, `bootstrap.py`, or any other module. Chat commands call `get_auth_context(config_path)` which returns either a real OAuth-backed `OrchidAuthContext` or the dev fallback — callers don't know or care which. **The CLI is an independent OAuth client** — it runs its own dance against the upstream IdP and is NOT one of the downstream consumers covered by the [auth-centralisation roadmap](../.knowledge/auth-centralisation.md) (which targets the MCP gateway + Next.js frontends).
 
 8. **Token storage at `~/.orchid/tokens.json`.** Permissions set to `0o600` (owner-only). Tokens are keyed by `client_id`, supporting multiple providers. Refresh tokens are used automatically when the access token expires.
 
+9. **Commands go through `commands/_session.py:resolve_session`.** Every command that needs both an `Orchid` instance and a per-user `OrchidAuthContext` calls `resolve_session(config_path)` (or its `session_context` async-context-manager wrapper), which bootstraps the framework, resolves auth, and warms `passthrough` / `oauth` MCP capability caches once per `(tenant_key, user_id)`. The interactive REPL stays alive across many turns; the warmer's idempotency check makes subsequent loop iterations a no-op. Failures in the per-user warm are logged and ignored — the chat still works, it just pays the lazy discovery cost on first tool call. `bootstrap()` itself warms `auth.mode: none` servers up front (no user identity needed).
+
 ## Commands
 
 ```bash
@@ -76,14 +81,16 @@ orchid chat share     --config <path> <id>     # Promote RAG to user scope
 
 # MCP server OAuth
 orchid mcp status    --config <path>           # Show OAuth status for MCP servers
-orchid mcp authorize <server> --config <path>  # Authorize via browser (PKCE)
 orchid mcp revoke    <server> --config <path>  # Revoke stored token
 
 # Config
 orchid config validate <agents.yaml>           # Validate agent config
 
 # RAG indexing
-orchid index seed     --config <path>          # Batch-index RAG data
+orchid index file <path> -n <namespace> --config <path>     # Index a single file
+orchid index dir  <path> -n <namespace> --config <path>     # Index a directory
+orchid index text "..."  -n <namespace> --config <path>     # Index inline text
+orchid index json-file <path> -n <namespace> --config <path>  # Bulk-index JSON entries
 
 # Skill generation (Claude Code)
 orchid skill generate <agents.yaml>            # Generate Claude Code skills

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 <!-- version list -->
 
+## v1.2.0 (2026-04-29)
+
+### Bug Fixes
+
+- **cli**: Centralize session handling and warm-up lifecycle
+  ([`cfe9c2d`](https://github.com/gadz82/orchid-cli/commit/cfe9c2de1cb39cd6002ff9a49bda2253ea25eee9))
+
+- **cli**: Ensure lock file path respects test monkeypatching of _ORCHID_DIR, enhance test for
+  temporary file cleanup
+  ([`471de32`](https://github.com/gadz82/orchid-cli/commit/471de32d515a54a34d568f2c87a74f34c0b66ca1))
+
+### Documentation
+
+- **cli**: Clarify CLI OAuth independence and auth-centralisation roadmap context
+  ([`da14aa6`](https://github.com/gadz82/orchid-cli/commit/da14aa6dc5b571e63ce7bd10a633133979ceba82))
+
+### Features
+
+- Bump orchid-ai dependency to >=1.4.0 in CLI and API
+  ([`9ed4940`](https://github.com/gadz82/orchid-cli/commit/9ed49401fe3c5337bef84a5c235e9bdc4bdaac3f))
+
+- **cli**: Enhance chat commands and RAG indexing, improve security for token storage
+  ([`74dac43`](https://github.com/gadz82/orchid-cli/commit/74dac433ce7731374f4bd4366cbee6c7ecf1dfc8))
+
+
 ## v1.1.4 (2026-04-22)
 
 ### Bug Fixes

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orchid-cli
-Version: 1.1.4
+Version: 1.2.0
 Summary: Orchid CLI — command-line interface for the Orchid agent framework
 Project-URL: Homepage, https://github.com/gadz82/orchid
 Project-URL: Repository, https://github.com/gadz82/orchid
@@ -26,7 +26,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: langchain-core>=0.3.0
-Requires-Dist: orchid-ai>=1.3.5
+Requires-Dist: orchid-ai>=1.4.0
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
@@ -164,24 +164,17 @@ Manage per-server OAuth for MCP servers that declare `auth.mode: oauth` in `agen
 # Show authorization status for every OAuth-enabled MCP server
 orchid mcp status -c orchid.yml
 
-# Authorize a specific MCP server via browser (PKCE flow)
-orchid mcp authorize <server-name> -c orchid.yml
-orchid mcp authorize <server-name> -c orchid.yml --timeout 180
-
 # Revoke the stored token for a server
 orchid mcp revoke <server-name> -c orchid.yml
 ```
 
-Chat commands also **auto-authorize** any unauthorized MCP servers on first use — the CLI opens the browser, waits for consent, stores the token, and proceeds.
+Authorization itself runs through the API gateway's OAuth callback — the CLI's job is only to surface status and let the user revoke a stored token.
 
 ### RAG Indexing
 
-Seed the vector store with data, **on startup or any time later**:
+Index documents into the vector store, **on startup or any time later**:
 
 ```bash
-# Run the registered StaticIndexer (consumer-provided seed data)
-orchid index seed -c orchid.yml --tenant my-tenant
-
 # Index a single document (PDF, DOCX, XLSX, CSV, TXT, MD, PNG, JPG)
 orchid index file ./docs/faq.pdf -n support -c orchid.yml
 
@@ -354,6 +347,17 @@ When the access token expires and a refresh token is available, the CLI refreshe
 
 When `identity_resolver_class` is configured, the CLI calls the resolver after login to populate `tenant_key` and `user_id` from the OAuth token. These identity fields are cached in the token file so subsequent commands don't need the resolver. See the [orchid OrchidIdentityResolver ABC](../orchid/orchid_ai/core/identity.py) for the interface.
 
+> **Note:** the CLI is an **independent OAuth client** — it runs its own
+> authorization-code + PKCE dance against the upstream IdP and calls the
+> identity resolver locally. It does NOT use the
+> centralised `/auth/exchange-code` / `/auth/resolve-identity` /
+> `/auth/refresh-token` endpoints that the MCP gateway uses (Phases 1–5
+> of the [auth-centralisation roadmap](../.knowledge/auth-centralisation.md)).
+> The CLI ships with the upstream secret `client_id` baked into its config
+> because it's a desktop app, not a network service. A future migration
+> could route the CLI through the same endpoints to remove the
+> CLI-side `client_secret` / userinfo coupling — out of scope today.
+
 ### Dev Fallback
 
 When `auth.dev_bypass: true` or `auth.cli` is absent, the CLI uses a dummy token (`cli-token`, tenant=`cli`, user=`cli-user`). This is fully backward compatible -- existing configs without OAuth continue to work unchanged.

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/README.md

@@ -122,24 +122,17 @@ Manage per-server OAuth for MCP servers that declare `auth.mode: oauth` in `agen
 # Show authorization status for every OAuth-enabled MCP server
 orchid mcp status -c orchid.yml
 
-# Authorize a specific MCP server via browser (PKCE flow)
-orchid mcp authorize <server-name> -c orchid.yml
-orchid mcp authorize <server-name> -c orchid.yml --timeout 180
-
 # Revoke the stored token for a server
 orchid mcp revoke <server-name> -c orchid.yml
 ```
 
-Chat commands also **auto-authorize** any unauthorized MCP servers on first use — the CLI opens the browser, waits for consent, stores the token, and proceeds.
+Authorization itself runs through the API gateway's OAuth callback — the CLI's job is only to surface status and let the user revoke a stored token.
 
 ### RAG Indexing
 
-Seed the vector store with data, **on startup or any time later**:
+Index documents into the vector store, **on startup or any time later**:
 
 ```bash
-# Run the registered StaticIndexer (consumer-provided seed data)
-orchid index seed -c orchid.yml --tenant my-tenant
-
 # Index a single document (PDF, DOCX, XLSX, CSV, TXT, MD, PNG, JPG)
 orchid index file ./docs/faq.pdf -n support -c orchid.yml
 
@@ -312,6 +305,17 @@ When the access token expires and a refresh token is available, the CLI refreshe
 
 When `identity_resolver_class` is configured, the CLI calls the resolver after login to populate `tenant_key` and `user_id` from the OAuth token. These identity fields are cached in the token file so subsequent commands don't need the resolver. See the [orchid OrchidIdentityResolver ABC](../orchid/orchid_ai/core/identity.py) for the interface.
 
+> **Note:** the CLI is an **independent OAuth client** — it runs its own
+> authorization-code + PKCE dance against the upstream IdP and calls the
+> identity resolver locally. It does NOT use the
+> centralised `/auth/exchange-code` / `/auth/resolve-identity` /
+> `/auth/refresh-token` endpoints that the MCP gateway uses (Phases 1–5
+> of the [auth-centralisation roadmap](../.knowledge/auth-centralisation.md)).
+> The CLI ships with the upstream secret `client_id` baked into its config
+> because it's a desktop app, not a network service. A future migration
+> could route the CLI through the same endpoints to remove the
+> CLI-side `client_secret` / userinfo coupling — out of scope today.
+
 ### Dev Fallback
 
 When `auth.dev_bypass: true` or `auth.cli` is absent, the CLI uses a dummy token (`cli-token`, tenant=`cli`, user=`cli-user`). This is fully backward compatible -- existing configs without OAuth continue to work unchanged.

orchid_cli-1.2.0/orchid_cli/_typer_async.py

@@ -0,0 +1,40 @@
+"""Tiny decorator that lets Typer call ``async def`` command bodies.
+
+Vanilla Typer (and the underlying Click) don't await coroutines — an
+``async def`` command would print ``<coroutine ...>`` and exit. The
+``async_command`` decorator wraps a coroutine in a sync trampoline that
+Typer can register as a normal command, so command files stop carrying
+the boilerplate pair of ``def cmd(...): asyncio.run(_cmd(...))`` plus
+``async def _cmd(...)``.
+
+Usage
+-----
+
+    @app.command()
+    @async_command
+    async def create(title: str = "") -> None:
+        ...
+
+The two decorators must be in this order: ``@app.command()`` outermost
+(Typer registers the wrapper), ``@async_command`` inside (returns a
+sync callable for Typer to register).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Awaitable
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def async_command(func: Callable[..., Awaitable[T]]) -> Callable[..., T]:
+    """Wrap an ``async def`` Typer command body in :func:`asyncio.run`."""
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> T:
+        return asyncio.run(func(*args, **kwargs))
+
+    return wrapper

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/orchid_cli/auth/config.py

@@ -36,6 +36,13 @@ class OAuthProviderConfig:
     identity_resolver_class: str = ""
     # Optional domain (passed to OrchidIdentityResolver.resolve).
     domain: str = ""
+    # Optional ``client_secret`` for OAuth servers that register the CLI
+    # as a CONFIDENTIAL client (PKCE alone is not enough — the
+    # authorization server requires both the verifier AND the secret on
+    # the token endpoint).  Pure-public PKCE setups leave this empty.
+    # Mirrored to refresh-token grants too — see
+    # :func:`orchid_cli.auth.middleware._refresh_token`.
+    client_secret: str = ""
 
 
 def load_oauth_config(config_path: str) -> OAuthProviderConfig | None:
@@ -76,6 +83,11 @@ def load_oauth_config(config_path: str) -> OAuthProviderConfig | None:
     issuer = cli_section.get("issuer", "")
     auth_endpoint = cli_section.get("authorization_endpoint", "")
     token_endpoint = cli_section.get("token_endpoint", "")
+    # Optional secret for OAuth servers that require the CLI to
+    # authenticate as a CONFIDENTIAL client (PKCE alone is not enough
+    # — the token endpoint demands ``client_secret`` too).  Empty
+    # string for pure-public PKCE clients.
+    client_secret = cli_section.get("client_secret", "")
 
     # Carry forward top-level auth fields for identity resolution.
     identity_resolver_class = auth_section.get("identity_resolver_class", "")
@@ -89,6 +101,7 @@ def load_oauth_config(config_path: str) -> OAuthProviderConfig | None:
         issuer=issuer,
         identity_resolver_class=identity_resolver_class,
         domain=domain,
+        client_secret=client_secret,
     )
 
 
@@ -136,6 +149,7 @@ async def discover_oidc_endpoints(config: OAuthProviderConfig) -> OAuthProviderC
         issuer=config.issuer,
         identity_resolver_class=config.identity_resolver_class,
         domain=config.domain,
+        client_secret=config.client_secret,
     )
 
 

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/orchid_cli/auth/flow.py

@@ -52,6 +52,7 @@ async def run_login_flow(
         "auth_endpoint": config.authorization_endpoint,
         "token_endpoint": config.token_endpoint,
         "client_id": config.client_id,
+        "client_secret": config.client_secret,
         "scopes": config.scopes,
         "timeout": timeout,
         "success_title": "Authentication successful",

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/orchid_cli/auth/middleware.py

@@ -101,17 +101,62 @@ async def get_auth_context(
         logger.warning("[CLI Auth] Token expired and no refresh token. Run 'orchid auth login'.")
         return _DEV_AUTH
 
-    # Build OrchidAuthContext — use stored identity if available.
+    # ── Fast path — rebuild the typed subclass from the cache ──
+    #
+    # When the most recent login resolved an identity, both
+    # ``auth_class`` (FQN) and ``auth_state`` (the dict produced by
+    # ``OrchidAuthContext.to_storage_dict()``) were persisted on the
+    # token.  We rebuild the typed instance directly here — no
+    # network round-trip — and pass the fresh ``access_token`` /
+    # ``expires_at`` from the (possibly just-refreshed) token in
+    # case they rolled over.
+    if token.auth_class and token.auth_state:
+        try:
+            from orchid_ai.utils import import_class
+
+            cls = import_class(token.auth_class)
+            return cls.from_storage_dict(
+                access_token=token.access_token,
+                expires_at=token.expires_at,
+                state=dict(token.auth_state),
+            )
+        except Exception as exc:
+            # Cache restoration failed — most likely the resolver's
+            # subclass moved or its ``from_storage_dict`` got a
+            # breaking change.  Log loudly and fall through to the
+            # resolver (slow path); the operator will see the
+            # warning and can ``orchid auth login`` once to refresh
+            # the cache shape.
+            logger.warning(
+                "[CLI Auth] Cached identity rebuild failed (%s: %s) — falling back to live resolver",
+                type(exc).__name__,
+                exc,
+            )
+
+    # ── Slow path — call the resolver, then cache for next time ──
+    #
+    # Used on first login (cache empty), after a manual ``orchid
+    # auth logout``, OR when the cached subclass-class moved and we
+    # had to bail out of the fast path above.
     auth = OrchidAuthContext(
         access_token=token.access_token,
         tenant_key=token.tenant_key or "default",
         user_id=token.user_id or "cli-user",
         expires_at=token.expires_at,
+        extra=dict(token.extra) if token.extra else None,
     )
-
-    # Optionally resolve identity via OrchidIdentityResolver.
-    if cfg.identity_resolver_class and (not token.tenant_key or not token.user_id):
+    if cfg.identity_resolver_class:
         auth = await _resolve_identity(cfg, token, auth)
+        # Persist the freshly-resolved identity so the NEXT command
+        # takes the fast path above.  Mirror the same logic as
+        # ``commands/auth.py:_resolve_and_store_identity`` so a
+        # one-off ``orchid chat`` against a token that lost its
+        # cache (e.g. legacy tokens written before this feature
+        # existed) self-heals on first use.
+        if type(auth) is not OrchidAuthContext:
+            token.auth_class = f"{type(auth).__module__}.{type(auth).__qualname__}"
+            token.auth_state = auth.to_storage_dict()
+            saver(cfg.client_id, token)
 
     return auth
 
@@ -120,12 +165,21 @@ async def _refresh_token(
     config: OAuthProviderConfig,
     token: StoredToken,
 ) -> StoredToken:
-    """Use the refresh_token grant to obtain a new access token."""
-    payload = {
+    """Use the refresh_token grant to obtain a new access token.
+
+    Mirrors :func:`exchange_code_for_tokens` — when the OAuth server
+    treats the CLI as a confidential client, the refresh grant ALSO
+    needs ``client_secret`` in the form body.  Pure-public PKCE
+    deployments leave ``config.client_secret`` empty and the field is
+    omitted.
+    """
+    payload: dict[str, str] = {
         "grant_type": "refresh_token",
         "refresh_token": token.refresh_token,
         "client_id": config.client_id,
     }
+    if config.client_secret:
+        payload["client_secret"] = config.client_secret
 
     async with httpx.AsyncClient(timeout=30) as client:
         resp = await client.post(

{orchid_cli-1.1.4 → orchid_cli-1.2.0}/orchid_cli/auth/pkce.py

@@ -28,7 +28,9 @@ import base64
 import hashlib
 import html
 import logging
+import os
 import secrets
+import shlex
 import socket
 import webbrowser
 from dataclasses import dataclass
@@ -188,20 +190,36 @@ async def exchange_code_for_tokens(
     code_verifier: str,
     redirect_uri: str,
     client_id: str,
+    client_secret: str = "",
     timeout: float = 30.0,
 ) -> dict:
     """POST the authorization code to the token endpoint; return the JSON body.
 
+    ``client_secret`` is optional — populate it when the OAuth server
+    treats the CLI as a CONFIDENTIAL client (PKCE alone isn't enough
+    — the token endpoint demands the secret as well).  Sent as
+    ``client_secret_post`` (form-body field) per RFC 6749 §2.3.1
+    because that's what every OAuth server we've seen accepts and it
+    doesn't require pre-flight knowledge of which auth method the
+    server supports.
+
     Raises ``httpx.HTTPStatusError`` on non-2xx responses so callers can
     distinguish transport errors from OAuth errors.
+
+    Note: the equivalent ``curl`` invocation is rendered by
+    :func:`run_pkce_flow` (pre-flight when ``ORCHID_AUTH_DEBUG_CURL``
+    is set, post-mortem on failure regardless).  Putting the diagnostic
+    one level up keeps this primitive HTTP-only.
     """
-    payload = {
+    payload: dict[str, str] = {
         "grant_type": "authorization_code",
         "code": code,
         "redirect_uri": redirect_uri,
         "client_id": client_id,
         "code_verifier": code_verifier,
     }
+    if client_secret:
+        payload["client_secret"] = client_secret
 
     async with httpx.AsyncClient(timeout=timeout) as client:
         resp = await client.post(
@@ -213,6 +231,33 @@ async def exchange_code_for_tokens(
         return resp.json()
 
 
+def _build_curl(url: str, body: dict[str, str]) -> str:
+    """Render the equivalent ``curl`` command for a form-encoded POST.
+
+    Each field uses ``--data-urlencode`` so ``=`` / ``&`` / spaces
+    inside values can't break the line.  Output is single-line and
+    backslash-continued so it pastes cleanly into a terminal.
+    """
+    lines = [
+        f"curl -i -X POST {shlex.quote(url)} \\",
+        "  -H 'Accept: application/json' \\",
+        "  -H 'Content-Type: application/x-www-form-urlencoded' \\",
+    ]
+    items = list(body.items())
+    for i, (k, v) in enumerate(items):
+        sep = " \\" if i < len(items) - 1 else ""
+        lines.append(f"  --data-urlencode {shlex.quote(f'{k}={v}')}{sep}")
+    return "\n".join(
+        [
+            "",
+            "── orchid-cli token-exchange curl ─────────────",
+            *lines,
+            "───────────────────────────────────────────────",
+            "",
+        ]
+    )
+
+
 # ── High-level orchestration ──────────────────────────────────
 
 
@@ -238,6 +283,7 @@ async def run_pkce_flow(
     token_endpoint: str,
     client_id: str,
     scopes: str,
+    client_secret: str = "",
     timeout: float = 120.0,
     browser_opener: BrowserOpener = webbrowser.open,
     success_title: str = "Authorization complete",
@@ -293,6 +339,24 @@ async def run_pkce_flow(
     if callback.state != state:
         return PKCEFlowResult(success=False, error="State mismatch — possible CSRF")
 
+    # Build the exact request payload up-front so we can render the
+    # equivalent curl on failure (or when the debug env var is set).
+    exchange_payload: dict[str, str] = {
+        "grant_type": "authorization_code",
+        "code": callback.code,
+        "redirect_uri": redirect_uri,
+        "client_id": client_id,
+        "code_verifier": code_verifier,
+    }
+    if client_secret:
+        exchange_payload["client_secret"] = client_secret
+
+    debug_curl = os.environ.get("ORCHID_AUTH_DEBUG_CURL", "").strip().lower() not in ("", "0", "false", "no")
+    if debug_curl:
+        # Pre-flight dump — visible BEFORE the request goes out so the
+        # operator can copy it into another terminal and replay there.
+        print(_build_curl(token_endpoint, exchange_payload), flush=True)
+
     try:
         data = await exchange_code_for_tokens(
             token_endpoint=token_endpoint,
@@ -300,9 +364,24 @@ async def run_pkce_flow(
             code_verifier=code_verifier,
             redirect_uri=redirect_uri,
             client_id=client_id,
+            client_secret=client_secret,
         )
     except httpx.HTTPStatusError as exc:
-        return PKCEFlowResult(success=False, error=f"Token exchange failed (HTTP {exc.response.status_code})")
+        # Surface the upstream OAuth error verbatim — without it, every
+        # 400 looks the same and there's no way to tell ``invalid_grant``
+        # apart from ``invalid_client`` apart from ``redirect_uri``
+        # mismatch.  RFC 6749 §5.2 mandates the body be JSON with
+        # ``error`` + ``error_description`` fields, but some servers
+        # return text/html — try JSON first, fall back to raw text.
+        try:
+            body = exc.response.json()
+            detail = f"{body.get('error', '?')}: {body.get('error_description', body)}"
+        except Exception:
+            detail = (exc.response.text or "<empty body>")[:300]
+        return PKCEFlowResult(
+            success=False,
+            error=f"Token exchange failed (HTTP {exc.response.status_code}): {detail}",
+        )
     except Exception as exc:  # pragma: no cover — defensive
         return PKCEFlowResult(success=False, error=f"Token exchange failed: {exc}")