squackit 0.6.0__tar.gz → 0.7.0__tar.gz

{squackit-0.6.0 → squackit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squackit
-Version: 0.6.0
+Version: 0.7.0
 Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
 Project-URL: Homepage, https://github.com/teaguesterling/squackit
 Project-URL: Documentation, https://squackit.readthedocs.io

{squackit-0.6.0 → squackit-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.6.0"
+version = "0.7.0"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"

squackit-0.7.0/squackit/runtime.py

@@ -0,0 +1,167 @@
+"""In-memory runtime configuration for the squackit MCP server.
+
+Distinct from ProjectDefaults (which is inferred-at-startup + file-loaded
+overrides from .fledgling-python/config.toml). This module holds *session*
+state that the MCP `config()` tool reads and writes — wiped on server
+restart, no disk persistence.
+
+Env vars at launch seed the initial values (e.g. SQUACKIT_ACTIVE_ROOT set
+in .mcp.json env block). Resetting reverts to those env-seeded values, not
+hardcoded defaults.
+
+Shape mirrors jetsam.config.runtime; see retritis bench/config-endpoint-plan.md
+for the cross-suite design.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields, replace
+from typing import Any
+
+
+_ENV_PREFIX = "SQUACKIT_"
+
+_VALID_LOG_LEVELS = {"debug", "info", "warn", "warning", "error"}
+
+
+@dataclass
+class SquackitRuntimeConfig:
+    """Session-scoped runtime knobs for the squackit MCP server.
+
+    Common keys (suite-wide convention, also on jetsam):
+        active_root: fallback when a tool's `path=`/`root=` arg is omitted.
+            None means use the server's process cwd (today's behavior).
+        log_level: debug | info | warn | error.
+
+    Squackit-specific:
+        max_results_default: default cap for token-aware result truncation
+            when tools don't get an explicit max_results.
+        complexity_max_results_default: separate cap for `complexity` tool,
+            which is usually requested in smaller batches.
+        fts_cache_size: LRU size for per-root FTS indexes. Larger = more
+            roots cached cheaply; smaller = less RAM but more rebuilds.
+            Note: takes effect on NEW roots; existing cache entries keep
+            their slot until they age out naturally.
+    """
+
+    active_root: str | None = None
+    log_level: str = "info"
+    max_results_default: int = 50
+    complexity_max_results_default: int = 20
+    fts_cache_size: int = 8
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "SquackitRuntimeConfig":
+        """Build a config seeded from environment variables.
+
+        Variables read (each optional):
+            SQUACKIT_ACTIVE_ROOT
+            SQUACKIT_LOG_LEVEL
+            SQUACKIT_MAX_RESULTS_DEFAULT
+            SQUACKIT_COMPLEXITY_MAX_RESULTS_DEFAULT
+            SQUACKIT_FTS_CACHE_SIZE
+
+        Invalid values fall back to the dataclass default.
+        """
+        e = env if env is not None else os.environ
+        cfg = cls()
+
+        if v := e.get(f"{_ENV_PREFIX}ACTIVE_ROOT"):
+            cfg.active_root = v
+        if v := e.get(f"{_ENV_PREFIX}LOG_LEVEL"):
+            if v.lower() in _VALID_LOG_LEVELS:
+                cfg.log_level = v.lower()
+        if v := e.get(f"{_ENV_PREFIX}MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}COMPLEXITY_MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.complexity_max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}FTS_CACHE_SIZE"):
+            try:
+                cfg.fts_cache_size = max(1, int(v))
+            except ValueError:
+                pass
+
+        return cfg
+
+    def to_dict(self) -> dict[str, Any]:
+        """Flat dict for the MCP `config()` response."""
+        return {f.name: getattr(self, f.name) for f in fields(self)}
+
+
+# Module-level singleton, seeded from env on import.
+_runtime: SquackitRuntimeConfig = SquackitRuntimeConfig.from_env()
+_seed: SquackitRuntimeConfig = replace(_runtime)
+
+
+def get_runtime() -> SquackitRuntimeConfig:
+    """Return the current runtime config."""
+    return _runtime
+
+
+def update_runtime(values: dict[str, Any]) -> SquackitRuntimeConfig:
+    """Merge values into the runtime config. Validates atomically.
+
+    Raises ValueError on unknown keys or invalid values, leaving the runtime
+    config unchanged.
+    """
+    global _runtime
+    valid_keys = {f.name for f in fields(SquackitRuntimeConfig)}
+    unknown = set(values) - valid_keys
+    if unknown:
+        raise ValueError(
+            f"unknown config key(s): {sorted(unknown)}. "
+            f"Valid keys: {sorted(valid_keys)}"
+        )
+
+    candidate = replace(_runtime)
+    for key, value in values.items():
+        _validate_one(key, value)
+        setattr(candidate, key, value)
+
+    _runtime = candidate
+    return _runtime
+
+
+def reset_runtime() -> SquackitRuntimeConfig:
+    """Reset to the env-seeded values captured at module import time."""
+    global _runtime
+    _runtime = replace(_seed)
+    return _runtime
+
+
+def resolve_scope_path(explicit_path: str | None = None) -> str:
+    """Resolve a scope path with the runtime config fallback chain.
+
+    Precedence: explicit_path -> runtime.active_root -> process cwd.
+    Used by tools that scope queries to a directory (investigate, etc.)
+    so a single `config(set={"active_root": X})` call configures the whole
+    session.
+    """
+    if explicit_path is not None:
+        return explicit_path
+    runtime_root = _runtime.active_root
+    if runtime_root is not None:
+        return runtime_root
+    return os.getcwd()
+
+
+def _validate_one(key: str, value: Any) -> None:
+    """Per-key value validation."""
+    if key == "log_level":
+        if not isinstance(value, str) or value.lower() not in _VALID_LOG_LEVELS:
+            raise ValueError(
+                f"log_level must be one of {sorted(_VALID_LOG_LEVELS)}, got {value!r}"
+            )
+    elif key in ("max_results_default", "complexity_max_results_default", "fts_cache_size"):
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ValueError(f"{key} must be a positive int, got {value!r}")
+    elif key == "active_root":
+        if value is not None and not isinstance(value, str):
+            raise ValueError(f"active_root must be str or None, got {type(value).__name__}")

{squackit-0.6.0 → squackit-0.7.0}/squackit/workflows.py

@@ -145,9 +145,11 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
             Only consulted when file_pattern is None.
     """
     if file_pattern is None:
-        import os
-        scope_path = path if path is not None else os.getcwd()
-        file_pattern = defaults.scoped_code_pattern(scope_path)
+        from squackit.runtime import resolve_scope_path
+        # Precedence: explicit path -> runtime.active_root -> process cwd.
+        # Runtime fallback lets a session set active_root once via
+        # `config(set={"active_root": X})` instead of passing path= per call.
+        file_pattern = defaults.scoped_code_pattern(resolve_scope_path(path))
 
     # 1. Find definitions matching the name
     try:
@@ -456,3 +458,28 @@ def register_workflows(mcp, con, defaults):
             ("query", str, _empty),
             ("file_pattern", Optional[str], None),
         ])
+
+    async def config_tool(*, set=None, reset=False):
+        from squackit.runtime import get_runtime, reset_runtime, update_runtime
+        if reset:
+            cfg = reset_runtime()
+            return cfg.to_dict()
+        if set:
+            try:
+                cfg = update_runtime(set)
+            except ValueError as e:
+                return {"error": "invalid_config", "message": str(e)}
+            return cfg.to_dict()
+        return get_runtime().to_dict()
+
+    _add_workflow_tool(mcp, "config",
+        "Read or update squackit's in-memory session config. Keys: active_root "
+        "(fallback for tools that take path=/root=), log_level, max_results_default, "
+        "complexity_max_results_default, fts_cache_size. In-memory only — wiped on "
+        "server restart. Env-var seeded at launch (SQUACKIT_ACTIVE_ROOT, etc). "
+        "config() reads; config(set={...}) merges atomically; config(reset=true) "
+        "reverts to env seed. Mirrors jetsam's config() endpoint.",
+        config_tool, [
+            ("set", Optional[dict], None),
+            ("reset", bool, False),
+        ])

squackit-0.7.0/tests/test_runtime_config.py

@@ -0,0 +1,175 @@
+"""Tests for the in-memory runtime config + MCP config() tool."""
+
+from __future__ import annotations
+
+import pytest
+
+from squackit import runtime as rt
+from squackit.runtime import (
+    SquackitRuntimeConfig,
+    get_runtime,
+    reset_runtime,
+    resolve_scope_path,
+    update_runtime,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_runtime():
+    """Reset the module singleton + seed between tests so order doesn't matter."""
+    rt._runtime = SquackitRuntimeConfig()
+    rt._seed = SquackitRuntimeConfig()
+    yield
+    rt._runtime = SquackitRuntimeConfig()
+    rt._seed = SquackitRuntimeConfig()
+
+
+class TestFromEnv:
+    def test_empty_env_returns_defaults(self):
+        cfg = SquackitRuntimeConfig.from_env(env={})
+        assert cfg.active_root is None
+        assert cfg.log_level == "info"
+        assert cfg.max_results_default == 50
+        assert cfg.complexity_max_results_default == 20
+        assert cfg.fts_cache_size == 8
+
+    def test_active_root_from_env(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_ACTIVE_ROOT": "/tmp/repo"})
+        assert cfg.active_root == "/tmp/repo"
+
+    def test_log_level_normalized_lowercase(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_LOG_LEVEL": "DEBUG"})
+        assert cfg.log_level == "debug"
+
+    def test_log_level_invalid_falls_back_to_default(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_LOG_LEVEL": "verbose"})
+        assert cfg.log_level == "info"
+
+    def test_int_field_from_env(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_MAX_RESULTS_DEFAULT": "100"})
+        assert cfg.max_results_default == 100
+
+    def test_int_field_invalid_falls_back(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_MAX_RESULTS_DEFAULT": "abc"})
+        assert cfg.max_results_default == 50
+
+    def test_int_field_zero_clamped_to_one(self):
+        cfg = SquackitRuntimeConfig.from_env(env={"SQUACKIT_FTS_CACHE_SIZE": "0"})
+        assert cfg.fts_cache_size == 1
+
+
+class TestUpdateRuntime:
+    def test_set_active_root_persists_in_singleton(self):
+        update_runtime({"active_root": "/tmp/x"})
+        assert get_runtime().active_root == "/tmp/x"
+
+    def test_unknown_key_raises_and_leaves_unchanged(self):
+        original = get_runtime().to_dict()
+        with pytest.raises(ValueError, match="unknown config key"):
+            update_runtime({"bogus": "value"})
+        assert get_runtime().to_dict() == original
+
+    def test_invalid_value_raises_and_leaves_unchanged(self):
+        original = get_runtime().to_dict()
+        with pytest.raises(ValueError, match="log_level"):
+            update_runtime({"log_level": "verbose"})
+        assert get_runtime().to_dict() == original
+
+    def test_atomic_batch_set_either_all_or_none(self):
+        original = get_runtime().to_dict()
+        with pytest.raises(ValueError):
+            update_runtime({"active_root": "/tmp/y", "log_level": "verbose"})
+        # active_root should NOT have been applied even though it's valid
+        assert get_runtime().to_dict() == original
+
+    def test_int_field_rejects_string(self):
+        with pytest.raises(ValueError, match="max_results_default"):
+            update_runtime({"max_results_default": "50"})
+
+    def test_int_field_rejects_bool(self):
+        # bool is an int subclass in Python — must reject explicitly
+        with pytest.raises(ValueError, match="max_results_default"):
+            update_runtime({"max_results_default": True})
+
+    def test_int_field_rejects_zero_or_negative(self):
+        with pytest.raises(ValueError, match="fts_cache_size"):
+            update_runtime({"fts_cache_size": 0})
+        with pytest.raises(ValueError, match="fts_cache_size"):
+            update_runtime({"fts_cache_size": -1})
+
+
+class TestResetRuntime:
+    def test_reset_reverts_to_seed(self, monkeypatch):
+        # Simulate launch-time env seed
+        monkeypatch.setenv("SQUACKIT_ACTIVE_ROOT", "/tmp/seeded")
+        rt._seed = SquackitRuntimeConfig.from_env()
+        rt._runtime = SquackitRuntimeConfig.from_env()
+        # Override at runtime
+        update_runtime({"active_root": "/tmp/overridden"})
+        assert get_runtime().active_root == "/tmp/overridden"
+        # Reset goes back to seed (not dataclass defaults)
+        reset_runtime()
+        assert get_runtime().active_root == "/tmp/seeded"
+
+    def test_reset_with_no_env_goes_to_defaults(self):
+        update_runtime({"active_root": "/tmp/x", "max_results_default": 200})
+        reset_runtime()
+        assert get_runtime().active_root is None
+        assert get_runtime().max_results_default == 50
+
+
+class TestResolveScopePath:
+    """Precedence: explicit -> runtime.active_root -> os.getcwd()."""
+
+    def test_explicit_wins(self, monkeypatch):
+        update_runtime({"active_root": "/tmp/runtime"})
+        monkeypatch.chdir("/tmp")
+        assert resolve_scope_path("/tmp/explicit") == "/tmp/explicit"
+
+    def test_runtime_active_root_used_when_explicit_none(self, monkeypatch):
+        update_runtime({"active_root": "/tmp/runtime"})
+        monkeypatch.chdir("/tmp")
+        assert resolve_scope_path(None) == "/tmp/runtime"
+
+    def test_cwd_used_when_both_none(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        assert resolve_scope_path(None) == str(tmp_path)
+
+
+class TestConfigToolViaMCP:
+    """Smoke tests for the registered MCP tool."""
+
+    @pytest.fixture(scope="class")
+    def mcp(self):
+        pytest.importorskip("fastmcp")
+        from conftest import PROJECT_ROOT
+        from squackit.server import create_server
+        return create_server(root=PROJECT_ROOT, init=False)
+
+    def test_config_is_registered(self, mcp):
+        import asyncio
+        async def _list():
+            from fastmcp import Client
+            async with Client(mcp) as client:
+                tools = await client.list_tools()
+                return [t.name for t in tools]
+        loop = asyncio.new_event_loop()
+        try:
+            names = loop.run_until_complete(_list())
+        finally:
+            loop.close()
+        assert "config" in names
+
+    def test_config_returns_current_state(self, mcp):
+        import asyncio
+        async def _call():
+            return await mcp.call_tool("config", {})
+        loop = asyncio.new_event_loop()
+        try:
+            result = loop.run_until_complete(_call())
+        finally:
+            loop.close()
+        # FastMCP wraps the dict in result.content[0].text as JSON
+        text = result.content[0].text if hasattr(result, "content") else str(result)
+        assert "active_root" in text
+        assert "max_results_default" in text