code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/claude_code_oauth/SETUP.md

@@ -0,0 +1,93 @@
+# Claude Code OAuth Plugin Setup Guide
+
+This guide walks you through using the Claude Code OAuth plugin inside Code Puppy.
+
+## Quick Start
+
+1. Ensure the plugin files live under `code_puppy/plugins/claude_code_oauth/`
+2. Restart Code Puppy so it loads the plugin
+3. Run `/claude-code-auth` and follow the prompts
+
+## Why No Client Registration?
+
+Anthropic exposes a shared **public client** (`claude-cli`) for command-line tools. That means:
+- No client secret is needed
+- Everyone authenticates through Claude Console
+- Security is enforced with PKCE and per-user tokens
+
+## Authentication Flow
+
+1. Call `/claude-code-auth`
+2. Your browser opens the Claude OAuth consent flow at `https://claude.ai/oauth/authorize`
+3. Sign in (or pick an account) and approve the "Claude CLI" access request
+4. The browser closes automatically after the redirect is captured
+5. Tokens are stored locally at `~/.code_puppy/claude_code_oauth.json`
+6. Available Claude Code models are fetched and added to `extra_models.json`
+
+## Commands Recap
+
+- `/claude-code-auth` – Authenticate and sync models
+- `/claude-code-status` – Show auth status, expiry, configured models
+- `/claude-code-logout` – Remove tokens and any models added by the plugin
+
+## Configuration Defaults
+
+`config.py` ships with values aligned to llxprt-code:
+
+```python
+CLAUDE_CODE_OAUTH_CONFIG = {
+    "auth_url": "https://claude.ai/oauth/authorize",
+    "token_url": "https://console.anthropic.com/v1/oauth/token",
+    "api_base_url": "https://api.anthropic.com",
+    "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    "scope": "org:create_api_key user:profile user:inference",
+    "redirect_host": "http://localhost",
+    "redirect_path": "callback",
+    "callback_port_range": (8765, 8795),
+    "callback_timeout": 180,
+    "prefix": "claude-code-",
+    "default_context_length": 200000,
+    "api_key_env_var": "CLAUDE_CODE_ACCESS_TOKEN",
+}
+```
+
+Change these only if Anthropic updates their endpoints or scopes.
+
+## After Authentication
+
+- Models appear in `~/.code_puppy/extra_models.json` with the `claude-code-` prefix
+- The environment variable `CLAUDE_CODE_ACCESS_TOKEN` is used by those models
+- `/claude-code-status` shows token expiry when the API provides it
+
+## Troubleshooting Tips
+
+- **Browser did not open** – Copy the displayed URL into your browser manually
+- **Invalid code** – The code expires quickly; generate a new one in Claude Console
+- **State mismatch** – Rare, but rerun `/claude-code-auth` if the browser reports a mismatch
+- **No models added** – Your account might lack Claude Code access; tokens are still stored for later use
+
+## Files Created
+
+```
+~/.code_puppy/
+├── claude_code_oauth.json   # OAuth tokens (0600 permissions)
+└── extra_models.json        # Extended model registry
+```
+
+## Manual Testing
+
+Run the helper script for sanity checks:
+
+```bash
+python code_puppy/plugins/claude_code_oauth/test_plugin.py
+```
+
+It verifies imports, configuration values, and filesystem expectations without hitting the Anthropic API.
+
+## Security Notes
+
+- Tokens are stored locally and never transmitted elsewhere
+- PKCE protects the flow even without a client secret
+- HTTPS endpoints are enforced for all requests
+
+Enjoy hacking with Claude Code straight from Code Puppy! 🐶💻

code_puppy_core_plugins/claude_code_oauth/__init__.py

@@ -0,0 +1,25 @@
+"""
+Claude Code OAuth Plugin for Code Puppy
+
+This plugin provides OAuth authentication for Claude Code and automatically
+adds available models to the extra_models.json configuration.
+
+The plugin also includes a token refresh heartbeat for maintaining fresh
+tokens during long-running agentic operations.
+"""
+
+from .token_refresh_heartbeat import (
+    TokenRefreshHeartbeat,
+    force_token_refresh,
+    get_current_heartbeat,
+    is_heartbeat_running,
+    token_refresh_heartbeat_context,
+)
+
+__all__ = [
+    "TokenRefreshHeartbeat",
+    "token_refresh_heartbeat_context",
+    "is_heartbeat_running",
+    "get_current_heartbeat",
+    "force_token_refresh",
+]

code_puppy_core_plugins/claude_code_oauth/config.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+from typing import Any, Dict
+
+from code_puppy import config
+
+# Claude Code OAuth configuration
+CLAUDE_CODE_OAUTH_CONFIG: Dict[str, Any] = {
+    # OAuth endpoints inferred from official Claude Code OAuth flow
+    "auth_url": "https://claude.ai/oauth/authorize",
+    "token_url": "https://console.anthropic.com/v1/oauth/token",
+    "api_base_url": "https://api.anthropic.com",
+    # OAuth client configuration observed in Claude Code CLI flow
+    "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    "scope": "org:create_api_key user:profile user:inference",
+    # Callback handling (we host a localhost callback to capture the redirect)
+    "redirect_host": "http://localhost",
+    "redirect_path": "callback",
+    "callback_port_range": (8765, 8795),
+    "callback_timeout": 180,
+    # Console redirect fallback (for manual flows, if needed)
+    "console_redirect_uri": "https://console.anthropic.com/oauth/code/callback",
+    # Local configuration (uses XDG_DATA_HOME)
+    "token_storage": None,  # Set dynamically in get_token_storage_path()
+    # Model configuration
+    "prefix": "claude-code-",
+    "default_context_length": 200000,
+    "long_context_length": 1000000,
+    "long_context_models": [
+        "claude-opus-4-6",
+        "claude-opus-4-7",
+        "claude-opus-4-8",
+        "claude-opus-5",
+        "claude-sonnet-5",
+        "claude-fable-5",
+    ],
+    "api_key_env_var": "CLAUDE_CODE_ACCESS_TOKEN",
+    "anthropic_version": "2023-06-01",
+}
+
+
+def get_token_storage_path() -> Path:
+    """Get the path for storing OAuth tokens (uses XDG_DATA_HOME)."""
+    data_dir = Path(config.DATA_DIR)
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return data_dir / "claude_code_oauth.json"
+
+
+def get_config_dir() -> Path:
+    """Get the Code Puppy configuration directory (uses XDG_CONFIG_HOME)."""
+    config_dir = Path(config.CONFIG_DIR)
+    config_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return config_dir
+
+
+def get_claude_models_path() -> Path:
+    """Get the path to the dedicated claude_models.json file (uses XDG_DATA_HOME)."""
+    data_dir = Path(config.DATA_DIR)
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return data_dir / "claude_models.json"

code_puppy_core_plugins/claude_code_oauth/fast_mode.py

@@ -0,0 +1,122 @@
+"""Fast mode support for Claude Code OAuth.
+
+Fast mode adds two wire-level changes when enabled via the per-model
+``fast`` setting:
+
+1. ``speed: "fast"`` is injected into the ``/v1/messages`` request payload.
+2. ``fast-mode-2026-02-01`` is appended to the ``anthropic-beta`` header.
+
+The setting is read at request time (not model construction time) so that
+toggling takes effect on the next call without a full agent reload for the
+payload side. The beta header must still be present on the httpx client at
+construction time, so we set that up once and rely on the existing
+interleaved-thinking pattern for consistency.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, MutableMapping
+
+# Anthropic beta marker for fast mode. Keep as a module-level constant so
+# there's one source of truth for both header setup and tests.
+FAST_MODE_BETA = "fast-mode-2026-02-01"
+
+# Per-model setting key, stored/read via get_all_model_settings. Deliberately NOT
+# get_effective_model_settings: it filters through model_supports_setting(), whose
+# claude-* allowlist lacks plugin-owned keys like ``fast``, silently dropping them.
+FAST_SETTING_KEY = "fast"
+
+
+def is_fast_mode_enabled(model_name: str) -> bool:
+    """Return True if the ``fast`` setting is on for ``model_name``."""
+    # Imported lazily to avoid circular imports at module load.
+    from code_puppy.config import get_all_model_settings
+
+    settings = get_all_model_settings(model_name)
+    return bool(settings.get(FAST_SETTING_KEY, False))
+
+
+def ensure_fast_beta_header(headers: MutableMapping[str, str], enabled: bool) -> None:
+    """Add or remove ``fast-mode-2026-02-01`` from the anthropic-beta header.
+
+    Mutates ``headers`` in place. Mirrors the interleaved-thinking handling so
+    beta markers stay comma-separated and de-duplicated.
+    """
+    existing = headers.get("anthropic-beta")
+    if existing:
+        parts = [p.strip() for p in existing.split(",") if p.strip()]
+    else:
+        parts = []
+
+    has_marker = FAST_MODE_BETA in parts
+    if enabled and not has_marker:
+        parts.append(FAST_MODE_BETA)
+    elif not enabled and has_marker:
+        parts = [p for p in parts if p != FAST_MODE_BETA]
+
+    if parts:
+        headers["anthropic-beta"] = ",".join(parts)
+    elif "anthropic-beta" in headers:
+        del headers["anthropic-beta"]
+
+
+def _inject_speed_in_payload(payload: Dict[str, Any]) -> None:
+    """Inject ``speed: "fast"`` into a /v1/messages payload dict in place."""
+    if not isinstance(payload, dict):
+        return
+    # Respect an explicit speed already present (don't clobber caller intent).
+    if "speed" not in payload:
+        payload["speed"] = "fast"
+
+
+def make_fast_mode_wrapper(
+    original_create: Callable[..., Any], model_name: str
+) -> Callable[..., Any]:
+    """Wrap ``messages.create`` to inject ``speed: fast`` when enabled.
+
+    The setting is re-read on every call so toggling via ``/claude-code-fast``
+    takes effect on the very next request (no agent reload needed for the
+    payload side of the equation).
+    """
+
+    async def wrapped_create(*args: Any, **kwargs: Any):
+        if is_fast_mode_enabled(model_name):
+            if kwargs:
+                _inject_speed_in_payload(kwargs)
+            elif args:
+                maybe_payload = args[-1]
+                if isinstance(maybe_payload, dict):
+                    _inject_speed_in_payload(maybe_payload)
+
+        return await original_create(*args, **kwargs)
+
+    return wrapped_create
+
+
+def patch_anthropic_client_fast_mode(client: Any, model_name: str) -> None:
+    """Monkey-patch ``messages.create`` (and ``beta.messages.create``).
+
+    Must be called *after* ``patch_anthropic_client_messages`` so our wrapper
+    sits outside the cache-control injector — order of wrappers doesn't matter
+    for correctness here, but keeping fast-mode outermost makes it easy to
+    reason about.
+    """
+    try:
+        messages_obj = getattr(client, "messages", None)
+        if messages_obj is not None and hasattr(messages_obj, "create"):
+            messages_obj.create = make_fast_mode_wrapper(
+                messages_obj.create, model_name
+            )
+    except Exception:  # pragma: no cover - defensive
+        pass
+
+    try:
+        beta_obj = getattr(client, "beta", None)
+        if beta_obj is not None:
+            beta_messages_obj = getattr(beta_obj, "messages", None)
+            if beta_messages_obj is not None and hasattr(beta_messages_obj, "create"):
+                beta_messages_obj.create = make_fast_mode_wrapper(
+                    beta_messages_obj.create, model_name
+                )
+    except Exception:  # pragma: no cover - defensive
+        pass

code_puppy_core_plugins/claude_code_oauth/prompt_handler.py

@@ -0,0 +1,64 @@
+"""Prompt preparation logic for Claude Code OAuth models.
+
+This module owns everything that's special about preparing prompts for
+``claude-code-*`` models:
+
+- The fixed system-instruction string Anthropic's Claude Code CLI expects.
+- The ``is_claude_code_model`` predicate.
+- A callback wired into the ``prepare_model_prompt`` hook which runs inside
+  ``code_puppy.model_utils.prepare_prompt_for_model``.
+
+Keeping this here (rather than in core ``model_utils``) keeps the core
+model-agnostic and lets the claude-code behavior ship/fail as a single
+plugin — exactly per the Contributing guide.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# System-prompt override the Claude Code CLI expects. For OAuth claude-code models the
+# real system prompt moves into the user turn instead (see the callback below).
+CLAUDE_CODE_INSTRUCTIONS = "You are Claude Code, Anthropic's official CLI for Claude."
+
+# Prefix used by every claude-code-* model (as registered by this plugin).
+_CLAUDE_CODE_PREFIX = "claude-code"
+
+
+def is_claude_code_model(model_name: str) -> bool:
+    """Return True if ``model_name`` is a claude-code OAuth model."""
+    return model_name.startswith(_CLAUDE_CODE_PREFIX)
+
+
+def get_claude_code_instructions() -> str:
+    """Return the fixed Claude Code system instruction string."""
+    return CLAUDE_CODE_INSTRUCTIONS
+
+
+def prepare_claude_code_prompt(
+    model_name: str,
+    system_prompt: str,
+    user_prompt: str,
+    prepend_system_to_user: bool = True,
+) -> Optional[Dict[str, Any]]:
+    """Callback for the ``prepare_model_prompt`` hook.
+
+    For claude-code models, swap in the Anthropic-expected instruction string
+    and (optionally) fold the caller's system prompt into the user message.
+
+    Returns ``None`` for non-claude-code models so other handlers / the
+    default passthrough can take over.
+    """
+    if not is_claude_code_model(model_name):
+        return None
+
+    modified_prompt = user_prompt
+    if prepend_system_to_user and system_prompt:
+        modified_prompt = f"{system_prompt}\n\n{user_prompt}"
+
+    return {
+        "handled": True,
+        "instructions": CLAUDE_CODE_INSTRUCTIONS,
+        "user_prompt": modified_prompt,
+        "is_claude_code": True,
+    }