code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/claude_code_hooks/config.py

@@ -0,0 +1,188 @@
+"""
+Configuration loader for Claude Code hooks.
+
+Loads and merges hooks from multiple locations:
+1. ~/.muse/hooks.json (global level) - always loaded if exists
+2. .claude/settings.json (project-level) - merged with global
+
+Both configurations are loaded and merged so that hooks from both levels
+coexist and execute together.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from code_muse.hook_engine.trust import compute_content_hash, is_hook_trusted
+
+logger = logging.getLogger(__name__)
+
+PROJECT_HOOKS_FILE = ".claude/settings.json"
+GLOBAL_HOOKS_FILE = Path("~/.muse/hooks.json").expanduser()
+
+
+def _deep_merge_hooks(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """
+    Merge hook configurations, combining event types and hook groups.
+
+    When the same event type exists in both base and overlay, their hook groups
+    are concatenated (overlay hooks appear after base hooks).
+
+    Args:
+        base: Base configuration dictionary
+        overlay: Configuration to merge on top
+
+    Returns:
+        Merged configuration with all hooks from both sources
+    """
+    merged = dict(base)
+
+    for event_type, hook_groups in overlay.items():
+        if event_type.startswith("_"):
+            # Skip comment keys
+            merged[event_type] = hook_groups
+            continue
+
+        if event_type not in merged:
+            # New event type, just add it
+            merged[event_type] = hook_groups
+        elif isinstance(merged[event_type], list) and isinstance(hook_groups, list):
+            # Both are lists, concatenate them (overlay hooks come after)
+            merged[event_type] = merged[event_type] + hook_groups
+            logger.debug(
+                f"Merged {len(hook_groups)} hook group(s) for event '{event_type}'"
+            )
+        else:
+            # Type mismatch or unexpected structure, keep base
+            logger.warning(
+                f"Cannot merge event type '{event_type}': type mismatch or unexpected structure"
+            )
+
+    return merged
+
+
+def load_hooks_config() -> dict[str, Any | None]:
+    """
+    Load and merge hooks configuration from available sources.
+
+    Priority order:
+    1. ~/.muse/hooks.json (global level) - always loaded if exists
+    2. .claude/settings.json (project-level) - merged with global
+
+    Returns:
+        Merged configuration dictionary or None if no config found.
+        This function preserves backward compatibility; trust metadata
+        is handled separately via load_hooks_config_with_sources().
+    """
+    config, _sources = load_hooks_config_with_sources()
+    return config
+
+
+def load_hooks_config_with_sources() -> tuple[dict[str, Any | None], list[dict]]:
+    """
+    Load and merge hooks configuration from available sources with trust metadata.
+
+    Priority order:
+    1. ~/.muse/hooks.json (global level) - always loaded if exists
+    2. .claude/settings.json (project-level) - merged with global
+
+    Returns:
+        Tuple of (merged configuration dictionary, list of source metadata dicts).
+        Each source metadata dict contains:
+            - path: file path
+            - source: "global" | "project"
+            - config: the raw hooks dict from this source
+            - content_hash: SHA-256 of file content
+            - trusted: bool
+    """
+    merged_config: dict[str, Any] = {}
+    sources: list[dict] = []
+
+    # Load global hooks first
+    global_config_path = Path(GLOBAL_HOOKS_FILE)
+
+    if global_config_path.exists():
+        try:
+            raw = global_config_path.read_text(encoding="utf-8")
+            config = json.loads(raw)
+            hooks_part = None
+            if "hooks" in config and isinstance(config["hooks"], dict):
+                logger.info(
+                    f"Loaded hooks configuration (wrapped format) from {GLOBAL_HOOKS_FILE}"
+                )
+                hooks_part = config["hooks"]
+            elif isinstance(config, dict):
+                logger.info(f"Loaded hooks configuration from {GLOBAL_HOOKS_FILE}")
+                hooks_part = config
+            if hooks_part is not None:
+                merged_config = _deep_merge_hooks(merged_config, hooks_part)
+                sources.append(
+                    {
+                        "path": str(global_config_path),
+                        "source": "global",
+                        "config": hooks_part,
+                        "content_hash": compute_content_hash(raw),
+                        "trusted": True,
+                    }
+                )
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in {GLOBAL_HOOKS_FILE}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to load {GLOBAL_HOOKS_FILE}: {e}", exc_info=True)
+
+    # Load and merge project-level hooks
+    project_config_path = Path.cwd() / PROJECT_HOOKS_FILE
+
+    if project_config_path.exists():
+        try:
+            raw = project_config_path.read_text(encoding="utf-8")
+            config = json.loads(raw)
+            hooks_config = config.get("hooks")
+            if hooks_config:
+                logger.info(f"Merging hooks configuration from {project_config_path}")
+                merged_config = _deep_merge_hooks(merged_config, hooks_config)
+                content_hash = compute_content_hash(raw)
+                project_root = Path.cwd().resolve()
+                trusted = is_hook_trusted(
+                    project_root,
+                    project_config_path.resolve(),
+                    content_hash,
+                )
+                sources.append(
+                    {
+                        "path": str(project_config_path),
+                        "source": "project",
+                        "config": hooks_config,
+                        "content_hash": content_hash,
+                        "trusted": trusted,
+                    }
+                )
+            else:
+                logger.debug(f"No 'hooks' section found in {project_config_path}")
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in {project_config_path}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to load {project_config_path}: {e}", exc_info=True)
+
+    if not merged_config:
+        logger.debug("No hooks configuration found")
+        return None, sources
+
+    event_count = len([event for event in merged_config if not event.startswith("_")])
+    logger.info(f"Hooks configuration ready ({event_count} event type(s))")
+    return merged_config, sources
+
+
+def get_hooks_config_paths() -> list[Path]:
+    """
+    Return list of hook configuration paths.
+
+    Returns paths in order of precedence (project-level first, then global).
+    Note: internally, hooks are loaded in reverse order (global first, then project)
+    so that project-level hooks can extend/append to global hooks.
+    """
+    return [
+        Path.cwd() / PROJECT_HOOKS_FILE,
+        GLOBAL_HOOKS_FILE,
+    ]

code_muse/plugins/claude_code_hooks/register_callbacks.py

@@ -0,0 +1,208 @@
+"""
+Register callbacks for Claude Code hooks plugin.
+
+Integrates the hook engine with code_muse's callback system.
+"""
+
+import logging
+from typing import Any
+
+from code_muse.callbacks import register_callback
+from code_muse.hook_engine import EventData, HookEngine
+
+from .config import load_hooks_config_with_sources
+
+_SUBAGENT_NAMES = frozenset(
+    {
+        "pack_leader",
+        "bloodhound",
+        "muse",
+        "code_muse",
+        "retriever",
+        "shepherd",
+        "terrier",
+        "watchdog",
+        "subagent",
+        "sub_agent",
+    }
+)
+
+logger = logging.getLogger(__name__)
+
+_hook_engine: HookEngine | None = None
+
+
+def _initialize_engine() -> HookEngine | None:
+    from code_muse.hook_engine.models import HookRegistry
+    from code_muse.hook_engine.registry import build_registry_from_config
+
+    merged_config, sources = load_hooks_config_with_sources()
+
+    if not merged_config:
+        logger.info("No hooks configuration found - Claude Code hooks disabled")
+        return None
+
+    try:
+        # Build registry per-source so project hooks can be marked untrusted
+        registry = HookRegistry()
+        for source_info in sources:
+            source = source_info.get("source", "global")
+            trusted = source_info.get("trusted", source == "global")
+            cfg = source_info.get("config", {})
+            if not cfg:
+                continue
+            sub_registry = build_registry_from_config(
+                cfg,
+                source=source,  # type: ignore[arg-type]
+                trusted=trusted,
+            )
+            # Merge sub_registry into main registry
+            for attr_name in [
+                "pre_tool_use",
+                "post_tool_use",
+                "session_start",
+                "session_end",
+                "pre_compact",
+                "user_prompt_submit",
+                "notification",
+                "stop",
+                "subagent_stop",
+            ]:
+                for hook in getattr(sub_registry, attr_name, []):
+                    registry.add_hook(attr_name, hook)
+
+        engine = HookEngine(strict_validation=False)
+        engine._registry = registry
+        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,
+) -> dict[str, Any | None]:
+    """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_muse 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_muse/plugins/claude_code_oauth/README.md

@@ -0,0 +1,167 @@
+# Claude Code OAuth Plugin
+
+This plugin adds OAuth authentication for Claude Code to Muse, 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 Muse 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 `~/.muse/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 `~/.muse/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 Muse (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 Muse
+
+## 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_muse/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 Muse.
+
+## Quick Start
+
+1. Ensure the plugin files live under `code_muse/plugins/claude_code_oauth/`
+2. Restart Muse 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 `~/.muse/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 `~/.muse/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
+
+```
+~/.muse/
+├── 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_muse/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 Muse.

code_muse/plugins/claude_code_oauth/__init__.py

@@ -0,0 +1,25 @@
+"""
+Claude Code OAuth Plugin for Muse
+
+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",
+]