snodo-core 0.7.2__py3-none-any.whl

snodo/config.py

@@ -0,0 +1,546 @@
+"""Configuration and API key management for Snodo.
+
+FILE: snodo/config.py
+
+Manages user configuration stored at ~/.snodo/config.yml:
+- API key storage with secure file permissions (600)
+- Model selection defaults
+- Key validation via liteLLM
+"""
+
+import os
+import stat
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from snodo.paths import resolve_home
+
+
+class ProviderConfig(BaseModel):
+    """Provider configuration with API credential env var and /models endpoint."""
+    api_key: str = ""
+    api_key_env: str = ""
+    models_endpoint: str = ""
+    account_id: str = ""
+    account_id_env: str = ""
+    base_url: str = ""
+    litellm_provider: str = ""
+    extra_headers: Dict[str, str] = Field(default_factory=dict)
+    probe_model: str = ""
+
+
+DEFAULT_PROVIDER_CATALOG: Dict[str, ProviderConfig] = {
+    "anthropic": ProviderConfig(
+        api_key_env="ANTHROPIC_API_KEY",
+        models_endpoint="https://api.anthropic.com/v1/models",
+        probe_model="claude-3-haiku-20240307",
+    ),
+    "openai": ProviderConfig(
+        api_key_env="OPENAI_API_KEY",
+        models_endpoint="https://api.openai.com/v1/models",
+        probe_model="gpt-4o-mini",
+    ),
+    "openrouter": ProviderConfig(
+        api_key_env="OPENROUTER_API_KEY",
+        models_endpoint="https://openrouter.ai/api/v1/models",
+        probe_model="openai/gpt-4o-mini",
+    ),
+    "google": ProviderConfig(
+        api_key_env="GEMINI_API_KEY",
+        models_endpoint="https://generativelanguage.googleapis.com/v1beta/models",
+        probe_model="gemini/gemini-2.0-flash",
+    ),
+    "cloudflare": ProviderConfig(
+        api_key_env="CLOUDFLARE_API_KEY",
+        account_id_env="CLOUDFLARE_ACCOUNT_ID",
+        models_endpoint="https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/models",
+        extra_headers={"x-session-affinity": "{task_id}"},
+        probe_model="@cf/meta/llama-3.1-8b-instruct",
+    ),
+    "deepseek": ProviderConfig(
+        api_key_env="DEEPSEEK_API_KEY",
+        models_endpoint="https://api.deepseek.com/models",
+        probe_model="deepseek/deepseek-chat",
+    ),
+}
+
+
+DEFAULT_MODEL = "claude-sonnet-4-20250514"
+
+
+# Provider-to-model prefix mapping for key resolution
+PROVIDER_MODEL_PREFIXES = {
+    "openai": ["gpt-", "o1-", "o3-"],
+    "anthropic": ["claude-"],
+    "google": ["gemini/", "gemini-"],
+    "cloudflare": ["cloudflare/", "openai/@cf/", "@cf/"],
+    "deepseek": ["deepseek/"],
+}
+
+# Alias map: litellm provider name → snodo config key.
+# litellm.get_llm_provider() returns "gemini" but snodo's config
+# key is "google".  Other names pass through unchanged.
+_PROVIDER_ALIASES: dict[str, str] = {
+    "gemini": "google",
+}
+
+
+def _set_api_key_env(mgr: "ConfigManager", model: str) -> None:
+    """Set API key in environment if available from config."""
+    api_key = mgr.get_key_for_model(model)
+    if api_key:
+        provider_name = ConfigManager._provider_for_model(model)
+        if provider_name:
+            providers = mgr.get_providers()
+            pc = providers.get(provider_name)
+            if pc and pc.api_key_env:
+                os.environ[pc.api_key_env] = api_key
+            if pc and pc.account_id_env and pc.account_id:
+                os.environ[pc.account_id_env] = pc.account_id
+            if pc and pc.litellm_provider:
+                target_pc = DEFAULT_PROVIDER_CATALOG.get(pc.litellm_provider)
+                if target_pc and target_pc.api_key_env:
+                    os.environ[target_pc.api_key_env] = api_key
+
+
+@contextmanager
+def provider_env(model: str):
+    """Injects provider API keys for model into os.environ."""
+    mgr = ConfigManager()
+    _set_api_key_env(mgr, model)
+    try:
+        yield mgr
+    finally:
+        pass  # env vars intentionally left set
+
+
+class ConfigError(Exception):
+    """Configuration error."""
+
+
+class ConfigManager:
+    """Manages Snodo user configuration.
+
+    Config file: ~/.snodo/config.yml
+    Enforces 600 permissions on the config file.
+    """
+
+    def __init__(self, config_dir: Optional[Path] = None):
+        """Initialize config manager.
+
+        Args:
+            config_dir: Override config directory (default: ~/.snodo)
+        """
+        self.config_dir = config_dir or resolve_home()
+        self.config_path = self.config_dir / "config.yml"
+
+    def load(self) -> dict:
+        """Load configuration from disk.
+
+        Returns:
+            Configuration dict (empty dict if file doesn't exist)
+
+        Raises:
+            ConfigError: If config.yml uses the legacy ``api_keys`` format
+                instead of the ``providers`` section.
+        """
+        if not self.config_path.exists():
+            return self._default_config()
+
+        try:
+            with open(self.config_path) as f:
+                data = yaml.safe_load(f) or {}
+        except yaml.YAMLError as e:
+            raise ConfigError(f"Invalid config file: {e}") from e
+
+        # Reject legacy api_keys-only configs — providers is the only schema
+        if data.get("api_keys") and not data.get("providers"):
+            raise ConfigError(
+                "Legacy api_keys config detected. "
+                "Migrate to the providers section. See docs."
+            )
+
+        # Ensure required keys exist
+        data.setdefault("model", DEFAULT_MODEL)
+        data.setdefault("engine", {"max_subtask_depth": 3, "max_session_age_days": 30, "token_ttl_seconds": 600})
+        return data
+
+    def _default_config(self) -> dict:
+        return {
+            "model": DEFAULT_MODEL,
+            "engine": {"max_subtask_depth": 3, "max_session_age_days": 30, "token_ttl_seconds": 600},
+            "cloud": {
+                "api_key": "",
+                "api_url": "https://api.snodo.dev",
+                "sync_enabled": False,
+            },
+            "mcp": {
+                "port": 55441,
+            },
+            "opencode": {
+                "session_token_warning": 150000,
+                "session_reset_on_model_change": False,
+            },
+        }
+
+    def get_providers(self) -> Dict[str, ProviderConfig]:
+        """Return configured providers, merged with defaults.
+
+        Config.yml ``providers`` section overrides default catalog entries.
+        Unlisted providers get their default values.
+        """
+        config = self.load()
+        providers_raw = config.get("providers", {})
+
+        result: Dict[str, ProviderConfig] = {}
+        if isinstance(providers_raw, dict):
+            for name, raw in providers_raw.items():
+                if isinstance(raw, dict):
+                    result[name] = ProviderConfig(**raw)
+
+        # Merge in defaults for providers not in config
+        for name, pc in DEFAULT_PROVIDER_CATALOG.items():
+            if name not in result:
+                result[name] = pc
+        return result
+
+    @staticmethod
+    def resolve_api_base(model: str) -> Optional[str]:
+        """Return the API base URL for *model*'s provider, or ``None``.
+
+        Checks the provider's ``base_url`` in the merged provider config.
+        """
+        provider = ConfigManager._provider_for_model(model)
+        if provider is None:
+            return None
+        pc = ConfigManager().get_providers().get(provider)
+        if pc and pc.base_url:
+            return pc.base_url
+        return None
+
+    @staticmethod
+    def resolve_litellm_provider(model: str) -> Optional[str]:
+        """Return the provider string litellm should route as for *model*."""
+        provider_key = ConfigManager._provider_for_model(model)
+        if not provider_key:
+            return None
+        pc = ConfigManager().get_providers().get(provider_key)
+        if pc and pc.litellm_provider:
+            return pc.litellm_provider
+        return provider_key
+
+    @staticmethod
+    def resolve_litellm_model(model: str) -> str:
+        """Return the model string formatted for litellm completion.
+
+        If a provider specifies a litellm_provider (e.g. litellm_provider="openai"
+        for provider block "ollama"), formats model as "openai/<model_id>" so litellm
+        routes it properly to the OpenAI-compatible endpoint.
+        """
+        provider_key = ConfigManager._provider_for_model(model)
+        if not provider_key:
+            return model
+        pc = ConfigManager().get_providers().get(provider_key)
+        if pc and pc.litellm_provider:
+            if model.startswith(f"{provider_key}/"):
+                raw_id = model[len(provider_key) + 1:]
+            else:
+                raw_id = model
+            return f"{pc.litellm_provider}/{raw_id}"
+        return model
+
+    @staticmethod
+    def resolve_extra_headers(model: str, task_id: Optional[str] = None) -> Optional[Dict[str, str]]:
+        """Return extra headers configured for model's provider.
+
+        Evaluates template variables like ``{task_id}`` in header values.
+        """
+        provider_key = ConfigManager._provider_for_model(model)
+        if not provider_key:
+            return None
+        pc = ConfigManager().get_providers().get(provider_key)
+        if not pc or not pc.extra_headers:
+            return None
+        tid = task_id or "unknown"
+        headers = {}
+        for k, v in pc.extra_headers.items():
+            headers[k] = v.replace("{task_id}", tid)
+        return headers or None
+
+    @staticmethod
+    def _provider_for_model(model: str) -> Optional[str]:
+        """Return the provider (snodo config key) for a model string.
+
+        Checks PROVIDER_MODEL_PREFIXES first, then configured provider block
+        names (e.g. "ollama/llama3" → "ollama"), and falls back to litellm's
+        get_llm_provider().
+        """
+        if not model:
+            return None
+
+        # 1. Match against PROVIDER_MODEL_PREFIXES
+        for provider, prefixes in PROVIDER_MODEL_PREFIXES.items():
+            for prefix in prefixes:
+                if model.startswith(prefix):
+                    return provider
+
+        # 2. Check if model starts with a configured provider key + "/"
+        providers = ConfigManager().get_providers()
+        if "/" in model:
+            prefix = model.split("/")[0]
+            if prefix in providers:
+                return prefix
+
+        # 3. litellm.get_llm_provider()
+        try:
+            from litellm import get_llm_provider
+            _model, provider_name, _, _ = get_llm_provider(model)
+        except Exception:
+            provider_name = None
+
+        if provider_name:
+            aliased = _PROVIDER_ALIASES.get(provider_name, provider_name)
+            if aliased in providers:
+                return aliased
+            return provider_name
+
+        return None
+
+    def save(self, config: dict) -> None:
+        """Save configuration to disk with secure permissions.
+
+        Args:
+            config: Configuration dict to save
+        """
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        with open(self.config_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False)
+
+        # Set file permissions to 600 (owner read/write only)
+        os.chmod(self.config_path, stat.S_IRUSR | stat.S_IWUSR)
+
+    def add_key(self, provider: str, key: str) -> None:
+        """Store an API key for a provider.
+
+        Args:
+            provider: Provider name (e.g., "openai", "anthropic", "google")
+            key: API key string
+        """
+        if not provider:
+            raise ConfigError("Provider name cannot be empty")
+        if not key:
+            raise ConfigError("API key cannot be empty")
+
+        config = self.load()
+        providers = config.setdefault("providers", {})
+        provider_data = providers.setdefault(provider, {})
+        provider_data["api_key"] = key
+        self.save(config)
+
+    def get_key(self, provider: str) -> Optional[str]:
+        """Get an API key for a provider.
+
+        Args:
+            provider: Provider name
+
+        Returns:
+            API key string, or None if not configured
+        """
+        pc = self.get_providers().get(provider)
+        if pc and pc.api_key:
+            return pc.api_key
+        return None
+
+    def remove_key(self, provider: str) -> bool:
+        """Remove an API key for a provider.
+
+        Args:
+            provider: Provider name
+
+        Returns:
+            True if key was removed, False if it didn't exist
+        """
+        config = self.load()
+        providers_raw = config.get("providers", {})
+        if isinstance(providers_raw, dict):
+            entry = providers_raw.get(provider, {})
+            if isinstance(entry, dict) and "api_key" in entry:
+                del entry["api_key"]
+                self.save(config)
+                return True
+        return False
+
+    def get_key_for_model(self, model: str) -> Optional[str]:
+        """Resolve the API key needed for a given model.
+
+        Args:
+            model: Model identifier (e.g., "claude-sonnet-4-20250514", "gpt-4o")
+
+        Returns:
+            API key string, or None if no matching key found
+        """
+        provider = self._provider_for_model(model)
+        if provider is None:
+            return None
+        return self.get_key(provider)
+
+    def set_model(self, model: str) -> None:
+        """Set the default model.
+
+        Args:
+            model: Model identifier
+        """
+        config = self.load()
+        config["model"] = model
+        self.save(config)
+
+    def get_model(self) -> str:
+        """Get the configured default model.
+
+        Returns:
+            Model identifier
+        """
+        config = self.load()
+        return config.get("default_model") or config.get("model", DEFAULT_MODEL)
+
+    def get_engine_value(self, key: str, default: Any = None) -> Any:
+        """Get an engine configuration value.
+
+        Args:
+            key: Engine config key (e.g., "max_subtask_depth")
+            default: Default value if key not found
+
+        Returns:
+            Config value
+        """
+        config = self.load()
+        return config.get("engine", {}).get(key, default)
+
+    def set_engine_value(self, key: str, value: Any) -> None:
+        """Set an engine configuration value.
+
+        Args:
+            key: Engine config key
+            value: Value to set
+
+        Raises:
+            ValueError: If value fails validation
+        """
+        if key == "max_subtask_depth":
+            if not isinstance(value, int) or value < 1 or value > 10:
+                raise ValueError(f"max_subtask_depth must be an integer between 1 and 10, got {value}")
+        elif key == "max_session_age_days":
+            if not isinstance(value, int) or value < 1 or value > 365:
+                raise ValueError(f"max_session_age_days must be an integer between 1 and 365, got {value}")
+        elif key == "token_ttl_seconds":
+            if not isinstance(value, int) or value < 60 or value > 86400:
+                raise ValueError(f"token_ttl_seconds must be an integer between 60 and 86400, got {value}")
+
+        config = self.load()
+        engine = config.setdefault("engine", {})
+        engine[key] = value
+        self.save(config)
+
+    def test_keys(self) -> Dict[str, str]:
+        """Test all configured API keys via liteLLM.
+
+        Returns:
+            Dict of provider -> result status ("valid", "invalid", "untestable")
+        """
+        results = {}
+        providers = self.get_providers()
+
+        for name, pc in providers.items():
+            key = self.get_key(name)
+            if not key:
+                continue
+            results[name] = self._test_single_key(name, key, pc)
+
+        return results
+
+    def _test_single_key(self, provider: str, key: str, pc: Optional[ProviderConfig] = None) -> str:
+        """Test a single API key by making a minimal LLM call.
+
+        Args:
+            provider: Provider name
+            key: API key to test
+            pc: ProviderConfig with api_key_env and probe_model
+
+        Returns:
+            "valid", "invalid", or "untestable"
+        """
+        if pc is None:
+            pc = self.get_providers().get(provider) or DEFAULT_PROVIDER_CATALOG.get(provider)
+
+        if pc is None or not pc.probe_model:
+            return "untestable"
+
+        model = pc.probe_model
+
+        env_var = pc.api_key_env
+        if not env_var and not pc.litellm_provider:
+            return "untestable"
+
+        try:
+            from litellm import completion
+        except (ImportError, Exception):
+            return "untestable"
+
+        target_env_vars = []
+        if env_var:
+            target_env_vars.append((env_var, key))
+        if pc.litellm_provider:
+            target_pc = DEFAULT_PROVIDER_CATALOG.get(pc.litellm_provider)
+            if target_pc and target_pc.api_key_env:
+                target_env_vars.append((target_pc.api_key_env, key))
+        if pc.account_id_env and pc.account_id:
+            target_env_vars.append((pc.account_id_env, pc.account_id))
+
+        saved_env = {}
+        for ev, val in target_env_vars:
+            saved_env[ev] = os.environ.get(ev)
+            os.environ[ev] = val
+
+        try:
+            kwargs: dict[str, Any] = {
+                "model": ConfigManager.resolve_litellm_model(model),
+                "messages": [{"role": "user", "content": "hi"}],
+                "max_tokens": 1,
+            }
+            api_base = ConfigManager.resolve_api_base(model) or pc.base_url
+            if api_base:
+                kwargs["api_base"] = api_base
+            extra_headers = ConfigManager.resolve_extra_headers(model) or (pc.extra_headers if pc.extra_headers else None)
+            if extra_headers:
+                kwargs["extra_headers"] = extra_headers
+
+            completion(**kwargs)
+            return "valid"
+        except Exception:
+            return "invalid"
+        finally:
+            for ev, _ in target_env_vars:
+                old = saved_env.get(ev)
+                if old is not None:
+                    os.environ[ev] = old
+                elif ev in os.environ:
+                    del os.environ[ev]
+
+    @staticmethod
+    def mask_key(key: str) -> str:
+        """Mask an API key for display, showing only prefix and suffix.
+
+        Args:
+            key: Full API key
+
+        Returns:
+            Masked key (e.g., "sk-ab...xyz")
+        """
+        if len(key) <= 8:
+            return key[:2] + "***"
+        return key[:5] + "***" + key[-3:]

snodo/core/__init__.py

@@ -0,0 +1 @@
+""""""

snodo/core/interfaces.py

@@ -0,0 +1,132 @@
+"""Core interfaces for the Snodo protocol engine.
+
+All other modules implement against these contracts.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class AuditError(Exception):
+    """Audit log operation failed (e.g., I/O write failure)."""
+
+
+class ExecutionError(Exception):
+    """Task execution produced no usable artifacts."""
+
+
+class Coder(ABC):
+    """Implements tasks. Can be LLM or human or traditional tooling.
+
+    The engine offers every adapter several optional capabilities (a progress
+    sink, a workspace, a job/task id for correlation, and two behavioural
+    switches). These are DECLARED here, with defaults, so that "this adapter
+    does not support X" is a visible fact rather than a silently skipped
+    ``hasattr`` line (docs/architecture/coder-adapter-contract.md §3.1, #68).
+    An adapter that does not override a capability inherits the default; the
+    engine sets these attributes unconditionally, never behind a guard.
+    """
+
+    #: Workspace the coder reads/writes, injected by the engine when the task
+    #: runs under a workspace. None for adapters that do not use one.
+    workspace_mcp: Optional[Any] = None
+    #: Progress sink handed to the coder by the engine; an adapter that wants
+    #: per-turn progress emits here. None = the adapter reports no progress.
+    progress_callback: Optional[Any] = None
+    #: When True, the coder writes its changes to the working tree directly
+    #: and the executor must NOT replay the returned artifacts through
+    #: WorkspaceMCP (e.g. in-place adapters). Default False: the executor
+    #: writes the artifacts.
+    skip_workspace_write: bool = False
+    #: When True, the coder (or its base class) owns the commit and the
+    #: executor must NOT stage/commit. This does NOT waive the obligation that
+    #: produced work be observable and attributable — "coder produced nothing"
+    #: is a fault regardless of who commits. Default False: the executor
+    #: commits.
+    skip_engine_commit: bool = False
+    #: Correlation ids the engine injects so adapter-side logging/telemetry
+    #: can be attributed to a job and task. Empty when not set.
+    _job_id: str = ""
+    _task_id: str = ""
+    #: Recovery depth and attempt number (1-based) of the task being executed,
+    #: injected by the engine so per-turn telemetry can be grouped by depth.
+    _depth: int = 0
+    _attempt: int = 1
+    #: Model identifier the adapter is bound to. Used for default-model
+    #: resolution and coder-respawn checks; may be empty on simple adapters.
+    model: str = ""
+    #: When True, the coder has access to and observes test execution feedback
+    #: during implementation (e.g. LiteLLMAdapter with test runner access).
+    #: Default False: the coder does not observe tests.
+    observes_tests: bool = False
+
+    @abstractmethod
+    def implement(self, spec: 'TaskSpec') -> 'CodeArtifact':
+        """Generate code from specification."""
+
+
+class MCPServer(ABC):
+    """Tool boundary enforcement."""
+    
+    @abstractmethod
+    def execute_tool(self, tool_name: str, params: Dict[str, Any]) -> Any:
+        """Execute tool within capability boundary."""
+
+
+class Task(BaseModel):
+    """A unit of work."""
+    id: str
+    spec: str
+    parent_task_ref: Optional[str] = None
+    # The original task at the root of a recovery chain.  Recovery subtasks
+    # derive their id (``<root>_fix_N``) and their spec (original intent +
+    # accumulated failures) from the root, never from the immediately previous
+    # attempt — see ADR 021.
+    root_task_ref: Optional[str] = None
+    root_spec: Optional[str] = None
+    prior_failures: List[Dict[str, Any]] = Field(default_factory=list)
+    # Recovery provenance: files earlier attempts in the same recovery chain
+    # wrote in the cumulative worktree. This is ownership context, not a
+    # rewrite request.
+    attempt_provenance: List[Dict[str, Any]] = Field(default_factory=list)
+    # Recovery read-set: paths earlier attempts inspected (files read,
+    # directories listed). Paths only, never contents — the tree changes
+    # between attempts and a cached version must not become authoritative.
+    attempt_reads: List[Dict[str, Any]] = Field(default_factory=list)
+    depth: int = 0
+    flow_type: Optional[str] = None
+    wave_id: Optional[str] = None
+
+
+class ValidatorResult(BaseModel):
+    """Output from a single validator."""
+    validator_id: str
+    severity: Literal["pass", "warn", "blocker"]
+    justification: str
+    error: bool = False
+    cited_criteria: Optional[List[str]] = None
+    #: Pre-cap severity when a severity_cap downgraded this result; None otherwise.
+    severity_original: Optional[str] = None
+
+
+class TaskSpec(BaseModel):
+    """Specification for code generation."""
+    description: str
+    constraints: List[str]
+    memory_summary: str = ""
+    project_context: Dict[str, Any] = Field(default_factory=dict)
+
+
+class FileArtifact(BaseModel):
+    """A file operation emitted by the coder."""
+    path: str
+    content: str = ""
+    action: str = "write"  # "write" | "delete"
+
+
+class CodeArtifact(BaseModel):
+    """Generated code output — list of file operations."""
+    files: List[FileArtifact] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)