codepp 0.0.437__py3-none-any.whl

code_puppy/plugins/claude_code_hooks/register_callbacks.py

@@ -0,0 +1,175 @@
+"""
+Register callbacks for Claude Code hooks plugin.
+
+Integrates the hook engine with code_puppy's callback system.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from code_puppy.callbacks import register_callback
+from code_puppy.hook_engine import EventData, HookEngine
+
+from .config import load_hooks_config
+
+_SUBAGENT_NAMES = frozenset(
+    {
+        "pack_leader",
+        "bloodhound",
+        "husky",
+        "retriever",
+        "shepherd",
+        "terrier",
+        "watchdog",
+        "subagent",
+        "sub_agent",
+    }
+)
+
+logger = logging.getLogger(__name__)
+
+_hook_engine: Optional[HookEngine] = None
+
+
+def _initialize_engine() -> Optional[HookEngine]:
+    config = load_hooks_config()
+
+    if not config:
+        logger.info("No hooks configuration found - Claude Code hooks disabled")
+        return None
+
+    try:
+        engine = HookEngine(config, strict_validation=False)
+        stats = engine.get_stats()
+        logger.info(
+            f"Hook engine ready - Total: {stats['total_hooks']}, "
+            f"Enabled: {stats['enabled_hooks']}"
+        )
+        return engine
+    except Exception as e:
+        logger.error(f"Failed to initialize hook engine: {e}", exc_info=True)
+        return None
+
+
+_hook_engine = _initialize_engine()
+
+
+async def on_pre_tool_call_hook(
+    tool_name: str,
+    tool_args: Dict[str, Any],
+    context: Any = None,
+) -> Optional[Dict[str, Any]]:
+    """Pre-tool callback — executes hooks before tool runs. Can block."""
+    if not _hook_engine:
+        return None
+
+    event_data = EventData(
+        event_type="PreToolUse",
+        tool_name=tool_name,
+        tool_args=tool_args,
+        context={"context": context} if context else {},
+    )
+
+    try:
+        result = await _hook_engine.process_event("PreToolUse", event_data)
+
+        if result.blocked:
+            logger.debug(
+                f"Tool '{tool_name}' blocked by hook: {result.blocking_reason}"
+            )
+            return {
+                "blocked": True,
+                "reason": result.blocking_reason,
+                "error_message": result.blocking_reason,
+            }
+        return None
+    except Exception as e:
+        logger.error(f"Error in pre-tool hook: {e}", exc_info=True)
+        return None
+
+
+async def on_post_tool_call_hook(
+    tool_name: str,
+    tool_args: Dict[str, Any],
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Post-tool callback — executes hooks after tool completes (observation only)."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="PostToolUse",
+        tool_name=tool_name,
+        tool_args=tool_args,
+        context={"result": result, "duration_ms": duration_ms, "context": context},
+    )
+
+    try:
+        await _hook_engine.process_event("PostToolUse", event_data)
+    except Exception as e:
+        logger.error(f"Error in post-tool hook: {e}", exc_info=True)
+
+
+register_callback("pre_tool_call", on_pre_tool_call_hook)
+register_callback("post_tool_call", on_post_tool_call_hook)
+
+
+async def on_startup_hook() -> None:
+    """Startup callback — fires SessionStart hooks when code_puppy boots."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="SessionStart",
+        tool_name="session",
+        tool_args={},
+    )
+
+    try:
+        await _hook_engine.process_event("SessionStart", event_data)
+    except Exception as e:
+        logger.error(f"Error in SessionStart hook: {e}", exc_info=True)
+
+
+async def on_agent_run_end_hook(
+    agent_name: str,
+    model_name: str,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """agent_run_end callback — fires Stop or SubagentStop hooks."""
+    if not _hook_engine:
+        return
+
+    agent_lower = (agent_name or "").lower()
+    is_subagent = any(name in agent_lower for name in _SUBAGENT_NAMES)
+    event_type = "SubagentStop" if is_subagent else "Stop"
+
+    event_data = EventData(
+        event_type=event_type,
+        tool_name=agent_name or "agent",
+        tool_args={},
+        context={
+            "agent_name": agent_name,
+            "model_name": model_name,
+            "session_id": session_id,
+            "success": success,
+            "error": str(error) if error else None,
+        },
+    )
+
+    try:
+        await _hook_engine.process_event(event_type, event_data)
+    except Exception as e:
+        logger.error(f"Error in {event_type} hook: {e}", exc_info=True)
+
+
+register_callback("startup", on_startup_hook)
+register_callback("agent_run_end", on_agent_run_end_hook)
+
+logger.info("Claude Code hooks plugin registered")

code_puppy/plugins/claude_code_oauth/README.md

@@ -0,0 +1,167 @@
+# Claude Code OAuth Plugin
+
+This plugin adds OAuth authentication for Claude Code to Code Puppy, automatically importing available models into your configuration.
+
+## Features
+
+- **OAuth Authentication**: Secure OAuth flow for Claude Code using PKCE
+- **Automatic Model Discovery**: Fetches available models from the Claude API once authenticated
+- **Model Registration**: Automatically adds models to `extra_models.json` with the `claude-code-` prefix
+- **Token Management**: Secure storage of OAuth tokens in the Code Puppy config directory
+- **Browser Integration**: Launches the Claude OAuth consent flow automatically
+- **Callback Capture**: Listens on localhost to receive and process the OAuth redirect
+
+## Commands
+
+### `/claude-code-auth`
+Authenticate with Claude Code via OAuth and import available models.
+
+This will:
+1. Launch the Claude OAuth consent flow in your browser
+2. Walk you through approving access for the shared `claude-cli` client
+3. Capture the redirect from Claude in a temporary local callback server
+4. Exchange the returned code for access tokens and store them securely
+5. Fetch available models from Claude Code and add them to your configuration
+
+### `/claude-code-status`
+Check Claude Code OAuth authentication status and configured models.
+
+Shows:
+- Current authentication status
+- Token expiry information (if available)
+- Number and names of configured Claude Code models
+
+### `/claude-code-logout`
+Remove Claude Code OAuth tokens and imported models.
+
+This will:
+1. Remove stored OAuth tokens
+2. Remove all Claude Code models from `extra_models.json`
+
+## Setup
+
+### Prerequisites
+
+1. **Claude account** with access to the Claude Console developer settings
+2. **Browser access** to generate authorization codes
+
+### Configuration
+
+The plugin ships with sensible defaults in `config.py`:
+
+```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",
+}
+```
+
+These values mirror the public client used by llxprt-code. Adjust only if Anthropic changes their configuration.
+
+### Environment Variables
+
+After authentication, the models will reference:
+- `CLAUDE_CODE_ACCESS_TOKEN`: Automatically written by the plugin
+
+## Usage Example
+
+```bash
+# Authenticate with Claude Code
+/claude-code-auth
+
+# Check status
+/claude-code-status
+
+# Use a Claude Code model
+/set model claude-code-claude-3-5-sonnet-20241022
+
+# When done, logout
+/claude-code-logout
+```
+
+## Model Configuration
+
+After authentication, models will be added to `~/.code_puppy/extra_models.json`:
+
+```json
+{
+  "claude-code-claude-3-5-sonnet-20241022": {
+    "type": "anthropic",
+    "name": "claude-3-5-sonnet-20241022",
+    "custom_endpoint": {
+      "url": "https://api.anthropic.com",
+      "api_key": "$CLAUDE_CODE_ACCESS_TOKEN"
+    },
+    "context_length": 200000,
+    "oauth_source": "claude-code-plugin"
+  }
+}
+```
+
+## Security
+
+- **Token Storage**: Tokens are saved to `~/.code_puppy/claude_code_oauth.json` with `0o600` permissions
+- **PKCE Support**: Uses Proof Key for Code Exchange for enhanced security
+- **State Validation**: Checks the returned state (if provided) to guard against CSRF
+- **HTTPS Only**: All OAuth communications use HTTPS endpoints
+
+## Troubleshooting
+
+### Browser doesn't open
+- Manually visit the URL shown in the output
+- Check that a default browser is configured
+
+### Authentication fails
+- Ensure the browser completed the redirect back to Code Puppy (no pop-up blockers)
+- Retry if the window shows an error; codes expire quickly
+- Confirm network access to `claude.ai`
+
+### Models not showing up
+- Claude may not return the model list for your account; verify access manually
+- Check `/claude-code-status` to confirm authentication succeeded
+
+## Development
+
+### File Structure
+
+```
+claude_code_oauth/
+├── __init__.py
+├── register_callbacks.py  # Main plugin logic and command handlers
+├── config.py              # Configuration settings
+├── utils.py               # OAuth helpers and file operations
+├── README.md              # This file
+├── SETUP.md               # Quick setup guide
+└── test_plugin.py         # Manual test helper
+```
+
+### Key Components
+
+- **OAuth Flow**: Authorization code flow with PKCE and automatic callback capture
+- **Token Management**: Secure storage and retrieval helpers
+- **Model Discovery**: API integration for model fetching
+- **Plugin Registration**: Custom command handlers wired into Code Puppy
+
+## Notes
+
+- The plugin assumes Anthropic continues to expose the shared `claude-cli` OAuth client
+- Tokens are refreshed on subsequent API calls if the service returns refresh tokens
+- Models are prefixed with `claude-code-` to avoid collisions with other Anthropic models
+
+## Contributing
+
+When modifying this plugin:
+1. Maintain security best practices
+2. Test OAuth flow changes manually before shipping
+3. Update documentation for any configuration or UX changes
+4. Keep files under 600 lines; split into helpers when needed

code_puppy/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/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/plugins/claude_code_oauth/config.py

@@ -0,0 +1,52 @@
+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"],
+    "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"