orchid-cli 1.0.2__tar.gz → 1.0.4__tar.gz

{orchid_cli-1.0.2 → orchid_cli-1.0.4}/AGENTS.md

@@ -11,7 +11,13 @@ orchid-cli/
   orchid_cli/
     main.py          Typer entry point — registers sub-commands
     bootstrap.py     Shared startup: load config, build graph, init SQLite storage
+    auth/            OAuth 2.0 authentication (Authorization Code + PKCE)
+      config.py      OAuth provider settings from orchid.yml (OIDC discovery)
+      flow.py        PKCE flow: browser login, localhost callback, code exchange
+      token_store.py Secure token persistence (~/.orchid/tokens.json)
+      middleware.py   Token refresh + AuthContext builder
     commands/
+      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)
@@ -45,9 +51,18 @@ 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 `AuthContext` or the dev fallback — callers don't know or care which.
+
+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.
+
 ## Commands
 
 ```bash
+# Authentication (OAuth 2.0)
+orchid auth login  --config <path>             # Opens browser for OAuth login
+orchid auth status --config <path>             # Show current auth state
+orchid auth logout --config <path>             # Clear stored tokens
+
 # Chat operations
 orchid chat create    --config <path>          # Create new chat session
 orchid chat list      --config <path>          # List all chats
@@ -96,6 +111,32 @@ Chat ID prefix matching is supported (type first few chars of UUID).
 | Storage class | `orchid_ai.persistence.sqlite.SQLiteChatStorage` | `CHAT_STORAGE_CLASS` |
 | Storage DSN | `~/.orchid/chats.db` | `CHAT_DB_DSN` |
 
+## OAuth Configuration
+
+OAuth is configured via the `auth.cli` section in `orchid.yml`. When absent or when `auth.dev_bypass: true`, the CLI uses a dummy dev token (backward compatible).
+
+```yaml
+auth:
+  dev_bypass: false
+  identity_resolver_class: myapp.identity.Resolver   # optional — enriches AuthContext
+  domain: platform.example.com                        # optional — passed to resolver
+
+  cli:
+    client_id: my-cli-app
+    scopes: openid api
+
+    # Option A: OIDC auto-discovery (recommended)
+    issuer: https://auth.example.com
+
+    # Option B: Explicit endpoints
+    # authorization_endpoint: https://auth.example.com/oauth2/authorize
+    # token_endpoint: https://auth.example.com/oauth2/token
+```
+
+**Flow:** `orchid auth login` opens the browser → user authenticates → callback on `localhost` → code exchanged for tokens → stored at `~/.orchid/tokens.json`. All subsequent `orchid chat` commands use the stored token automatically, refreshing it when expired.
+
+**Auth resolution order in chat commands:** stored OAuth token → refresh if expired → identity resolver (optional) → fallback to dev token.
+
 ## Running
 
 ```bash
@@ -128,3 +169,5 @@ Requires Ollama running on host with models: `llama3.2`, `nomic-embed-text`.
 - `bootstrap()` sets `ORCHID_CONFIG` as an env var so the orchid library can find the YAML. Don't remove this.
 - Chat persistence auto-creates `~/.orchid/chats.db` on first run. The directory is created automatically.
 - Embedding dimension mismatch (768 vs 1536 vs 3072) causes silent retrieval failures. Switching models requires re-indexing Qdrant.
+- Running `orchid chat` against a config with OAuth-protected MCP servers without `orchid auth login` first — the CLI falls back to the dev token, and MCP servers return 401. Always run `orchid auth login -c <config>` first.
+- Token file permissions — `~/.orchid/tokens.json` should be `0o600` (owner-only). The CLI sets this automatically, but manual edits or copies may loosen permissions.

orchid_cli-1.0.4/CHANGELOG.md

@@ -0,0 +1,58 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.4 (2026-04-14)
+
+### Bug Fixes
+
+- **auth**: Improve token expiration messaging and log formatting
+  ([`7ef8e5b`](https://github.com/gadz82/orchid-cli/commit/7ef8e5b4bd33ade45b8ac07634c7b84e02808a5b))
+
+- **auth**: Integrate OAuth 2.0 PKCE flow and token storage into CLI auth commands
+  ([`e2df0b8`](https://github.com/gadz82/orchid-cli/commit/e2df0b8b261350382b94c8359abadab0007fdc6c))
+
+
+## v1.0.3 (2026-04-14)
+
+### Bug Fixes
+
+- Built-in tools args propagation fix.
+  ([`b12dd65`](https://github.com/gadz82/orchid-cli/commit/b12dd652fc61b35d5cc89a1d5df9dcc6fe841533))
+
+- Built-in tools parameter declarations in config.
+  ([`ce62103`](https://github.com/gadz82/orchid-cli/commit/ce621034f4ad307dd8203ab98b4eac4cc604969b))
+
+- Fixing ruff errors and updated dependency
+  ([`30bbf37`](https://github.com/gadz82/orchid-cli/commit/30bbf3701d30aa422d86a2906a8546377b026248))
+
+- Implement multi-turn LLM tool loop package version update
+  ([`97e0a1a`](https://github.com/gadz82/orchid-cli/commit/97e0a1a22d47ce4ad2387a68f9b588b8c81641f9))
+
+- Tools result context injection.
+  ([`fbdfdef`](https://github.com/gadz82/orchid-cli/commit/fbdfdef54da0e8a2df947b12fcfb8220cf488daf))
+
+
+## v1.0.2 (2026-04-13)
+
+### Bug Fixes
+
+- Removing external dependencies and improving error handling and final outcome for the user.
+  ([`2ebc6ef`](https://github.com/gadz82/orchid-cli/commit/2ebc6efb8f96e047a3dc649710967d4aece64ab4))
+
+
+## v1.0.1 (2026-04-13)
+
+### Bug Fixes
+
+- Orchid-cli package description and readme update.
+  ([`5055129`](https://github.com/gadz82/orchid-cli/commit/505512906fc9b6d88752940dd1c9b24a2eec8f0d))
+
+
+## v1.0.0 (2026-04-13)
+
+- Initial Release
+
+## v1.0.0 (2026-04-10)
+
+- Initial Release

{orchid_cli-1.0.2 → orchid_cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orchid-cli
-Version: 1.0.2
+Version: 1.0.4
 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.2.0
+Requires-Dist: orchid-ai>=1.2.13
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
@@ -64,6 +64,9 @@ The `orchid` command is available after installation.
 # Validate config:
 orchid config validate agents.yaml
 
+# Authenticate (required for configs with OAuth-protected MCP servers):
+orchid auth login -c orchid.yml
+
 # Start an interactive chat session:
 orchid chat interactive -c orchid.yml
 
@@ -74,6 +77,21 @@ orchid chat send <chat_id> "Hello!" -c orchid.yml
 
 ## Commands
 
+### Authentication
+
+```bash
+# Log in via OAuth (opens browser, exchanges code for tokens)
+orchid auth login -c orchid.yml
+
+# Check current auth status (token expiry, tenant, user)
+orchid auth status -c orchid.yml
+
+# Clear stored tokens
+orchid auth logout -c orchid.yml
+```
+
+Authentication is required when MCP servers or tools need a real Bearer token. When OAuth is not configured (`auth.dev_bypass: true` or no `auth.cli` section), a dev fallback token is used automatically.
+
 ### Chat Management
 
 ```bash
@@ -193,6 +211,17 @@ llm:
   model: ollama/llama3.2
 agents:
   config_path: agents.yaml
+auth:
+  dev_bypass: false                # set true to skip OAuth entirely
+  identity_resolver_class: myapp.identity.Resolver  # optional
+  domain: platform.example.com                       # optional
+  cli:
+    client_id: my-cli-app
+    scopes: openid api
+    issuer: https://auth.example.com          # OIDC auto-discovery
+    # OR explicit endpoints:
+    # authorization_endpoint: https://auth.example.com/oauth2/authorize
+    # token_endpoint: https://auth.example.com/oauth2/token
 rag:
   vector_backend: null      # no Qdrant needed for basic usage
 storage:
@@ -208,8 +237,38 @@ storage:
 | Vector backend | `qdrant` | `VECTOR_BACKEND` |
 | Storage class | `orchid.persistence.sqlite.SQLiteChatStorage` | `CHAT_STORAGE_CLASS` |
 | Storage DSN | `~/.orchid/chats.db` | `CHAT_DB_DSN` |
+| Token storage | `~/.orchid/tokens.json` | -- |
+
+Chat data is stored in SQLite at `~/.orchid/chats.db` by default. OAuth tokens are stored at `~/.orchid/tokens.json` with owner-only permissions (`0o600`). Both directories are created automatically on first use.
+
+## Authentication
+
+The CLI supports **OAuth 2.0 Authorization Code + PKCE** for authenticating with external services. This is a generic, provider-agnostic flow that works with any standard OAuth 2.0 / OIDC provider (Okta, Auth0, Keycloak, etc.).
+
+### How It Works
+
+1. `orchid auth login` opens the system browser to the provider's authorization page
+2. User authenticates and consents
+3. Provider redirects to a temporary `localhost` callback server
+4. CLI exchanges the authorization code for access + refresh tokens (with PKCE verification)
+5. Tokens are stored at `~/.orchid/tokens.json`
+6. All subsequent `orchid chat` commands use the stored token automatically
+
+### OIDC Discovery
+
+When `issuer` is set in the config, the CLI fetches `{issuer}/.well-known/openid-configuration` to auto-discover `authorization_endpoint` and `token_endpoint`. This is the recommended approach -- you only need the issuer URL.
+
+### Token Refresh
+
+When the access token expires and a refresh token is available, the CLI refreshes automatically before sending the request. If refresh fails, you'll be prompted to run `orchid auth login` again.
+
+### Identity Resolution
+
+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 IdentityResolver ABC](../orchid/orchid_ai/core/identity.py) for the interface.
+
+### Dev Fallback
 
-Chat data is stored in SQLite at `~/.orchid/chats.db` by default. The directory is created automatically on first run.
+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.
 
 ## Prerequisites
 
@@ -222,14 +281,20 @@ Chat data is stored in SQLite at `~/.orchid/chats.db` by default. The directory
 orchid_cli/
   main.py          Typer entry point -- registers sub-commands
   bootstrap.py     Shared startup: load config, build graph, init storage
+  auth/            OAuth 2.0 authentication (self-contained)
+    config.py      Provider settings from orchid.yml + OIDC discovery
+    flow.py        Authorization Code + PKCE flow (browser, localhost callback)
+    token_store.py Secure token persistence (~/.orchid/tokens.json)
+    middleware.py   Token refresh + AuthContext builder
   commands/
+    auth.py        login, logout, status subcommands
     chat.py        Full CRUD + messaging + interactive mode
     config.py      Validate agents.yaml
     index.py       Seed RAG vector store
     skill.py       Generate Claude Code skills from agents.yaml
 ```
 
-The CLI is a thin layer that calls `orchid` SDK functions and displays results via Rich.
+The CLI is a thin layer that calls `orchid` SDK functions and displays results via Rich. The `auth/` subpackage is fully self-contained -- no OAuth logic leaks into chat commands or bootstrap.
 
 ## Development
 

{orchid_cli-1.0.2 → orchid_cli-1.0.4}/README.md

@@ -22,6 +22,9 @@ The `orchid` command is available after installation.
 # Validate config:
 orchid config validate agents.yaml
 
+# Authenticate (required for configs with OAuth-protected MCP servers):
+orchid auth login -c orchid.yml
+
 # Start an interactive chat session:
 orchid chat interactive -c orchid.yml
 
@@ -32,6 +35,21 @@ orchid chat send <chat_id> "Hello!" -c orchid.yml
 
 ## Commands
 
+### Authentication
+
+```bash
+# Log in via OAuth (opens browser, exchanges code for tokens)
+orchid auth login -c orchid.yml
+
+# Check current auth status (token expiry, tenant, user)
+orchid auth status -c orchid.yml
+
+# Clear stored tokens
+orchid auth logout -c orchid.yml
+```
+
+Authentication is required when MCP servers or tools need a real Bearer token. When OAuth is not configured (`auth.dev_bypass: true` or no `auth.cli` section), a dev fallback token is used automatically.
+
 ### Chat Management
 
 ```bash
@@ -151,6 +169,17 @@ llm:
   model: ollama/llama3.2
 agents:
   config_path: agents.yaml
+auth:
+  dev_bypass: false                # set true to skip OAuth entirely
+  identity_resolver_class: myapp.identity.Resolver  # optional
+  domain: platform.example.com                       # optional
+  cli:
+    client_id: my-cli-app
+    scopes: openid api
+    issuer: https://auth.example.com          # OIDC auto-discovery
+    # OR explicit endpoints:
+    # authorization_endpoint: https://auth.example.com/oauth2/authorize
+    # token_endpoint: https://auth.example.com/oauth2/token
 rag:
   vector_backend: null      # no Qdrant needed for basic usage
 storage:
@@ -166,8 +195,38 @@ storage:
 | Vector backend | `qdrant` | `VECTOR_BACKEND` |
 | Storage class | `orchid.persistence.sqlite.SQLiteChatStorage` | `CHAT_STORAGE_CLASS` |
 | Storage DSN | `~/.orchid/chats.db` | `CHAT_DB_DSN` |
+| Token storage | `~/.orchid/tokens.json` | -- |
+
+Chat data is stored in SQLite at `~/.orchid/chats.db` by default. OAuth tokens are stored at `~/.orchid/tokens.json` with owner-only permissions (`0o600`). Both directories are created automatically on first use.
+
+## Authentication
+
+The CLI supports **OAuth 2.0 Authorization Code + PKCE** for authenticating with external services. This is a generic, provider-agnostic flow that works with any standard OAuth 2.0 / OIDC provider (Okta, Auth0, Keycloak, etc.).
+
+### How It Works
+
+1. `orchid auth login` opens the system browser to the provider's authorization page
+2. User authenticates and consents
+3. Provider redirects to a temporary `localhost` callback server
+4. CLI exchanges the authorization code for access + refresh tokens (with PKCE verification)
+5. Tokens are stored at `~/.orchid/tokens.json`
+6. All subsequent `orchid chat` commands use the stored token automatically
+
+### OIDC Discovery
+
+When `issuer` is set in the config, the CLI fetches `{issuer}/.well-known/openid-configuration` to auto-discover `authorization_endpoint` and `token_endpoint`. This is the recommended approach -- you only need the issuer URL.
+
+### Token Refresh
+
+When the access token expires and a refresh token is available, the CLI refreshes automatically before sending the request. If refresh fails, you'll be prompted to run `orchid auth login` again.
+
+### Identity Resolution
+
+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 IdentityResolver ABC](../orchid/orchid_ai/core/identity.py) for the interface.
+
+### Dev Fallback
 
-Chat data is stored in SQLite at `~/.orchid/chats.db` by default. The directory is created automatically on first run.
+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.
 
 ## Prerequisites
 
@@ -180,14 +239,20 @@ Chat data is stored in SQLite at `~/.orchid/chats.db` by default. The directory
 orchid_cli/
   main.py          Typer entry point -- registers sub-commands
   bootstrap.py     Shared startup: load config, build graph, init storage
+  auth/            OAuth 2.0 authentication (self-contained)
+    config.py      Provider settings from orchid.yml + OIDC discovery
+    flow.py        Authorization Code + PKCE flow (browser, localhost callback)
+    token_store.py Secure token persistence (~/.orchid/tokens.json)
+    middleware.py   Token refresh + AuthContext builder
   commands/
+    auth.py        login, logout, status subcommands
     chat.py        Full CRUD + messaging + interactive mode
     config.py      Validate agents.yaml
     index.py       Seed RAG vector store
     skill.py       Generate Claude Code skills from agents.yaml
 ```
 
-The CLI is a thin layer that calls `orchid` SDK functions and displays results via Rich.
+The CLI is a thin layer that calls `orchid` SDK functions and displays results via Rich. The `auth/` subpackage is fully self-contained -- no OAuth logic leaks into chat commands or bootstrap.
 
 ## Development
 

orchid_cli-1.0.4/orchid_cli/auth/__init__.py

@@ -0,0 +1,15 @@
+"""
+OAuth authentication for orchid-cli.
+
+Provides generic OAuth 2.0 Authorization Code + PKCE flow,
+token storage, and automatic refresh. Works with any standard
+OAuth 2.0 / OIDC provider.
+
+Usage::
+
+    from orchid_cli.auth.middleware import get_auth_context
+
+    auth = await get_auth_context(config_path="orchid.yml")
+"""
+
+from __future__ import annotations

orchid_cli-1.0.4/orchid_cli/auth/config.py

@@ -0,0 +1,148 @@
+"""
+OAuth provider configuration — parsed from the ``auth.cli`` section of orchid.yml.
+
+Supports two modes:
+  1. **OIDC discovery** — set ``issuer`` and endpoints are auto-discovered
+     via ``{issuer}/.well-known/openid-configuration``.
+  2. **Explicit endpoints** — set ``authorization_endpoint`` and
+     ``token_endpoint`` directly.
+
+When ``auth.dev_bypass: true`` or ``auth.cli`` is absent, the CLI falls
+back to the legacy hardcoded dummy token (no OAuth).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import httpx
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class OAuthProviderConfig:
+    """Resolved OAuth provider settings — ready to use."""
+
+    client_id: str
+    authorization_endpoint: str
+    token_endpoint: str
+    scopes: str = "openid"
+    # Optional OIDC issuer (informational after discovery).
+    issuer: str = ""
+    # Optional identity resolver class (for enriching AuthContext).
+    identity_resolver_class: str = ""
+    # Optional domain (passed to IdentityResolver.resolve).
+    domain: str = ""
+
+
+def load_oauth_config(config_path: str) -> OAuthProviderConfig | None:
+    """Load OAuth config from the ``auth.cli`` section of orchid.yml.
+
+    Returns ``None`` when:
+      - ``auth.dev_bypass`` is truthy, OR
+      - ``auth.cli`` section is absent or incomplete.
+    """
+    if not config_path:
+        return None
+
+    try:
+        with open(config_path) as f:
+            data = yaml.safe_load(f) or {}
+    except FileNotFoundError:
+        logger.warning("[CLI Auth] Config file %s not found", config_path)
+        return None
+
+    auth_section = data.get("auth", {})
+    if not isinstance(auth_section, dict):
+        return None
+
+    # dev_bypass means no OAuth
+    if _is_truthy(auth_section.get("dev_bypass", False)):
+        return None
+
+    cli_section = auth_section.get("cli", {})
+    if not isinstance(cli_section, dict) or not cli_section:
+        return None
+
+    client_id = cli_section.get("client_id", "")
+    if not client_id:
+        logger.warning("[CLI Auth] auth.cli.client_id is required for OAuth")
+        return None
+
+    scopes = cli_section.get("scopes", "openid")
+    issuer = cli_section.get("issuer", "")
+    auth_endpoint = cli_section.get("authorization_endpoint", "")
+    token_endpoint = cli_section.get("token_endpoint", "")
+
+    # Carry forward top-level auth fields for identity resolution.
+    identity_resolver_class = auth_section.get("identity_resolver_class", "")
+    domain = auth_section.get("domain", "")
+
+    return OAuthProviderConfig(
+        client_id=client_id,
+        authorization_endpoint=auth_endpoint,
+        token_endpoint=token_endpoint,
+        scopes=scopes,
+        issuer=issuer,
+        identity_resolver_class=identity_resolver_class,
+        domain=domain,
+    )
+
+
+async def discover_oidc_endpoints(config: OAuthProviderConfig) -> OAuthProviderConfig:
+    """Resolve endpoints via OIDC discovery if ``issuer`` is set but endpoints are missing.
+
+    Fetches ``{issuer}/.well-known/openid-configuration`` and extracts
+    ``authorization_endpoint`` and ``token_endpoint``.
+
+    If both endpoints are already set, returns ``config`` unchanged.
+    """
+    if config.authorization_endpoint and config.token_endpoint:
+        return config
+
+    if not config.issuer:
+        raise ValueError(
+            "OAuth config requires either 'issuer' (for OIDC discovery) "
+            "or explicit 'authorization_endpoint' + 'token_endpoint'."
+        )
+
+    discovery_url = f"{config.issuer.rstrip('/')}/.well-known/openid-configuration"
+    logger.info("[CLI Auth] Discovering OIDC endpoints from %s", discovery_url)
+
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(discovery_url)
+        resp.raise_for_status()
+        metadata = resp.json()
+
+    auth_ep = config.authorization_endpoint or metadata.get("authorization_endpoint", "")
+    token_ep = config.token_endpoint or metadata.get("token_endpoint", "")
+
+    if not auth_ep or not token_ep:
+        raise ValueError(
+            f"OIDC discovery at {discovery_url} did not provide "
+            f"authorization_endpoint ({auth_ep!r}) or token_endpoint ({token_ep!r})."
+        )
+
+    logger.info("[CLI Auth] Discovered: authorization=%s, token=%s", auth_ep, token_ep)
+
+    return OAuthProviderConfig(
+        client_id=config.client_id,
+        authorization_endpoint=auth_ep,
+        token_endpoint=token_ep,
+        scopes=config.scopes,
+        issuer=config.issuer,
+        identity_resolver_class=config.identity_resolver_class,
+        domain=config.domain,
+    )
+
+
+def _is_truthy(value: object) -> bool:
+    """Interpret YAML booleans and strings as truthy."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() in ("true", "1", "yes")
+    return bool(value)