studyctl 2.3.0__tar.gz → 2.4.0__tar.gz

{studyctl-2.3.0 → studyctl-2.4.0}/.gitignore

@@ -496,11 +496,6 @@ uv-*.lock
 
 # Iterate runner artefacts (autoresearch pattern — kept untracked)
 results.tsv
-eval-results.tsv
 .pytest-junit.xml
 docs/reports/
 docs/brainstorms/
-packages/studyctl/tests/results/
-
-# Dev-only tooling (autoresearch eval harness — not shipped to users)
-dev/

{studyctl-2.3.0 → studyctl-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: studyctl
-Version: 2.3.0
+Version: 2.4.0
 Summary: AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline
 Project-URL: Homepage, https://github.com/NetDevAutomate/socratic-study-mentor
 Project-URL: Repository, https://github.com/NetDevAutomate/socratic-study-mentor

{studyctl-2.3.0 → studyctl-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "studyctl"
-version = "2.3.0"
+version = "2.4.0"
 description = "AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline"
 requires-python = ">=3.12"
 readme = "README.md"
@@ -58,6 +58,7 @@ markers = [
 [tool.pyright]
 pythonVersion = "3.12"
 typeCheckingMode = "basic"
+extraPaths = ["../agent-session-tools/src"]  # workspace sibling for cross-package imports
 exclude = ["src/studyctl/tui", "src/studyctl/content", "src/studyctl/cli/_content.py", "src/studyctl/cli/_web.py", "src/studyctl/web", "src/studyctl/mcp", "src/studyctl/eval/llm_client.py"]  # optional deps not in CI
 
 [dependency-groups]

studyctl-2.4.0/src/studyctl/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""Agent adapter package — modular agent detection and launch.
+
+Usage:
+    from studyctl.adapters import detect_agents, get_adapter
+
+    agents = detect_agents()
+    adapter = get_adapter('claude')
+    persona = adapter.setup(content, session_dir)
+    cmd = adapter.launch_cmd(persona, resume=False)
+"""
+
+from studyctl.adapters._protocol import AdapterProtocol, AgentAdapter
+from studyctl.adapters.registry import (
+    detect_agents,
+    get_adapter,
+    get_all_adapters,
+    get_default_agent,
+    reset_registry,
+)
+
+__all__ = [
+    "AdapterProtocol",
+    "AgentAdapter",
+    "detect_agents",
+    "get_adapter",
+    "get_all_adapters",
+    "get_default_agent",
+    "reset_registry",
+]

studyctl-2.4.0/src/studyctl/adapters/_custom.py

@@ -0,0 +1,159 @@
+"""Config-driven factory for custom agent adapters.
+
+Reads the ``agents.custom`` section from config.yaml and builds
+``AgentAdapter`` instances at runtime. This allows users to add any
+CLI-based AI agent without modifying source code.
+
+Example config::
+
+    agents:
+      custom:
+        aider:
+          binary: aider
+          strategy: cli-flag
+          launch: "{binary} --read {persona}"
+          resume: "{binary} --read {persona} --resume"
+          env:
+            OPENAI_API_KEY: sk-...
+        my-agent:
+          binary: my-agent
+          strategy: cwd-file
+          filename: .context.md
+          launch: "{binary}"
+          teardown: "pkill -f my-agent"
+          mcp:
+            format: generic
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+
+from studyctl.adapters._protocol import AgentAdapter
+from studyctl.adapters._strategies import cli_flag_setup, cwd_file_setup, write_mcp_config
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# Supported strategy names → setup callables
+_STRATEGIES = {
+    "cli-flag": cli_flag_setup,
+    "cwd-file": cwd_file_setup,
+}
+
+
+def build_custom_adapter(name: str, config: dict) -> AgentAdapter:
+    """Build an ``AgentAdapter`` from a config dict.
+
+    Args:
+        name: The adapter name (key from ``agents.custom``).
+        config: The raw config dict for this adapter.
+
+    Returns:
+        A fully-constructed ``AgentAdapter`` instance.
+
+    Raises:
+        ValueError: If ``strategy`` is not ``"cli-flag"`` or ``"cwd-file"``.
+    """
+    binary: str = config["binary"]
+    strategy_name: str = config["strategy"]
+    launch_template: str = config["launch"]
+    resume_template: str = config.get("resume", launch_template)
+    env_vars: dict[str, str] = config.get("env", {}) or {}
+    teardown_cmd: str | None = config.get("teardown")
+    mcp_config = config.get("mcp")
+
+    # --- Strategy -----------------------------------------------------------
+    if strategy_name not in _STRATEGIES:
+        raise ValueError(
+            f"Unknown strategy {strategy_name!r} for adapter {name!r}. "
+            f"Must be one of: {sorted(_STRATEGIES)}"
+        )
+
+    if strategy_name == "cwd-file":
+        filename = config.get("filename", "PERSONA.md")
+        setup_fn = functools.partial(cwd_file_setup, filename=filename)
+    else:
+        setup_fn = _STRATEGIES[strategy_name]
+
+    # --- Launch command builder ---------------------------------------------
+    def _make_launch_cmd(persona_path: Path, resume: bool) -> str:
+        template = resume_template if resume else launch_template
+        resolved = shutil.which(binary) or binary
+        cmd = template.format(
+            binary=resolved,
+            persona=str(persona_path),
+            session_dir=str(persona_path.parent),
+        )
+        if env_vars:
+            prefix = " ".join(f"{k}={v}" for k, v in env_vars.items())
+            cmd = f"export {prefix}; {cmd}"
+        return cmd
+
+    # --- Teardown -----------------------------------------------------------
+    teardown_fn = None
+    if teardown_cmd:
+        _cmd = teardown_cmd  # capture in closure
+
+        def _teardown(_session_dir: Path) -> None:
+            try:
+                # shell=True is intentional: teardown_cmd is a user-supplied shell string
+                # (e.g. "pkill -f my-agent") that requires shell interpretation.
+                subprocess.run(_cmd, shell=True, timeout=10, check=False)  # nosec B602
+            except Exception as exc:
+                log.warning("Teardown command %r failed: %s", _cmd, exc)
+
+        teardown_fn = _teardown
+
+    # --- MCP setup ----------------------------------------------------------
+    mcp_fn = None
+    if mcp_config is not None:
+        if mcp_config is True:
+            _fmt = "generic"
+            _path = None
+        else:
+            _fmt = mcp_config.get("format", "generic")
+            _path = mcp_config.get("path")
+
+        def _mcp_setup(session_dir: Path) -> None:
+            write_mcp_config(session_dir, fmt=_fmt, path=_path)
+
+        mcp_fn = _mcp_setup
+
+    return AgentAdapter(
+        name=name,
+        binary=binary,
+        setup=setup_fn,
+        launch_cmd=_make_launch_cmd,
+        teardown=teardown_fn,
+        mcp_setup=mcp_fn,
+    )
+
+
+def load_custom_adapters() -> dict[str, AgentAdapter]:
+    """Load custom adapters from the ``agents.custom`` config section.
+
+    Returns:
+        Dict mapping adapter name → ``AgentAdapter``. Empty if no custom
+        adapters are configured or the config cannot be loaded.
+    """
+    from studyctl.settings import load_settings
+
+    customs = getattr(load_settings().agents, "custom", None)
+    if not customs:
+        return {}
+
+    result: dict[str, AgentAdapter] = {}
+    for adapter_name, adapter_config in customs.items():
+        try:
+            result[adapter_name] = build_custom_adapter(adapter_name, adapter_config)
+        except Exception as exc:
+            log.warning("Failed to build custom adapter %r: %s", adapter_name, exc)
+
+    return result

studyctl-2.4.0/src/studyctl/adapters/_local_llm.py

@@ -0,0 +1,46 @@
+"""Shared helpers for local LLM adapters (Ollama and LM Studio).
+
+Both adapters use Claude Code as the frontend but point it at a local
+LLM backend via environment variables. These helpers are extracted here
+to avoid duplication between ollama.py and lmstudio.py.
+"""
+
+from __future__ import annotations
+
+
+def _get_local_llm_config(provider: str) -> tuple[str, str]:
+    """Return (base_url, model) for a local LLM provider from config.
+
+    Falls back to sensible defaults if config isn't available.
+    """
+    defaults = {
+        "ollama": ("http://localhost:4000", "qwen3-coder"),  # LiteLLM proxy
+        "lmstudio": ("http://localhost:1234", "qwen3-coder"),
+    }
+    try:
+        from studyctl.settings import load_settings
+
+        cfg = getattr(load_settings().agents, provider, None)
+        if cfg and cfg.model:
+            return cfg.base_url or defaults[provider][0], cfg.model
+    except Exception:
+        pass
+    return defaults[provider]
+
+
+def _local_llm_env_prefix(base_url: str, auth_token: str, model: str) -> str:
+    """Build shell env var exports for a local LLM provider.
+
+    Tier-pins all Claude Code model tiers to the same model, since
+    local LLMs only serve one model at a time. Without this, Claude
+    tries to use different models for sub-agents and fast tasks.
+    """
+    return (
+        f"export ANTHROPIC_BASE_URL={base_url} "
+        f"ANTHROPIC_AUTH_TOKEN={auth_token} "
+        f"ANTHROPIC_MODEL={model} "
+        f"ANTHROPIC_SMALL_FAST_MODEL={model} "
+        f"ANTHROPIC_DEFAULT_HAIKU_MODEL={model} "
+        f"ANTHROPIC_DEFAULT_SONNET_MODEL={model} "
+        f"ANTHROPIC_DEFAULT_OPUS_MODEL={model}; "
+    )

studyctl-2.4.0/src/studyctl/adapters/_protocol.py

@@ -0,0 +1,53 @@
+"""Agent adapter Protocol and dataclass.
+
+The AdapterProtocol defines the contract that every agent adapter
+must satisfy. AgentAdapter is the concrete frozen dataclass that
+implements it using callables for each behaviour.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+@runtime_checkable
+class AdapterProtocol(Protocol):
+    """Contract for agent adapters.
+
+    Any object with these attributes and methods can act as an adapter.
+    The AgentAdapter dataclass satisfies this Protocol, but custom
+    implementations can use any class as long as it provides these fields.
+    """
+
+    name: str
+    binary: str
+
+    def setup(self, canonical_content: str, session_dir: Path) -> Path: ...
+    def launch_cmd(self, persona_path: Path, resume: bool) -> str: ...
+    def teardown(self, session_dir: Path) -> None: ...
+    def mcp_setup(self, session_dir: Path) -> None: ...
+
+
+@dataclass(frozen=True)
+class AgentAdapter:
+    """Configuration and behaviour for one AI coding agent.
+
+    Each field is either static data or a callable that handles
+    the agent-specific mechanism for persona injection and launch.
+    """
+
+    name: str
+    binary: str
+    setup: Callable[[str, Path], Path]
+    """(canonical_content, session_dir) -> persona_path"""
+    launch_cmd: Callable[[Path, bool], str]
+    """(persona_path, resume) -> shell command string"""
+    teardown: Callable[[Path], None] | None = None
+    """Optional cleanup for agents that write global state."""
+    mcp_setup: Callable[[Path], None] | None = None
+    """Optional MCP config writer for the session directory."""

studyctl-2.4.0/src/studyctl/adapters/_strategies.py

@@ -0,0 +1,165 @@
+"""Reusable persona injection strategies and MCP config writers.
+
+These are the building blocks for constructing AgentAdapter instances.
+Each strategy handles one specific mechanism (temp file, CWD file, MCP
+config) so adapter definitions remain declarative and DRY.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import tempfile
+from pathlib import Path
+
+
+def cli_flag_setup(canonical_content: str, _session_dir: Path) -> Path:
+    """Write persona to a secure temp file for agents that accept --flag /path.
+
+    Creates a file with 0o600 permissions (owner read/write only) so the
+    persona content is not world-readable on multi-user systems.
+
+    Args:
+        canonical_content: The rendered persona markdown content.
+        _session_dir: Unused; accepted to satisfy the setup callable signature.
+
+    Returns:
+        Path to the temporary file. Caller is responsible for cleanup.
+    """
+    fd, tmp = tempfile.mkstemp(suffix=".md", prefix="studyctl-persona-")
+    try:
+        os.write(fd, canonical_content.encode())
+    finally:
+        os.close(fd)
+
+    # Set secure permissions: owner read+write only
+    os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+
+    return Path(tmp)
+
+
+def cwd_file_setup(
+    canonical_content: str,
+    session_dir: Path,
+    *,
+    filename: str = "PERSONA.md",
+) -> Path:
+    """Write persona as a named file inside the session directory.
+
+    Used by agents (e.g. Kiro) that pick up context files from the CWD
+    rather than accepting an explicit flag.
+
+    Args:
+        canonical_content: The rendered persona markdown content.
+        session_dir: Directory where the persona file will be written.
+        filename: Name for the persona file. Defaults to ``PERSONA.md``.
+
+    Returns:
+        Path to the written file.
+    """
+    dest = session_dir / filename
+    dest.write_text(canonical_content, encoding="utf-8")
+    return dest
+
+
+# ---------------------------------------------------------------------------
+# MCP config writer
+# ---------------------------------------------------------------------------
+
+
+def _mcp_command() -> list[str]:
+    """Return the command list for launching studyctl-mcp.
+
+    Checks PATH first so installed tool users get the fast path. Falls
+    back to ``uv run`` against the workspace package so development
+    checkouts work without a separate install step.
+
+    Returns:
+        A list suitable for use as ``command + args`` in an MCP config.
+    """
+    if shutil.which("studyctl-mcp"):
+        return ["studyctl-mcp"]
+
+    # Repo root is six levels up from this file:
+    # packages/studyctl/src/studyctl/adapters/_strategies.py
+    #                                          ^adapters
+    #                                 ^studyctl
+    #                        ^src
+    #               ^studyctl  (package)
+    #      ^packages
+    # ^repo_root
+    repo_root = Path(__file__).parent.parent.parent.parent.parent.parent
+    return [
+        "uv",
+        "run",
+        "--project",
+        str(repo_root / "packages" / "studyctl"),
+        "studyctl-mcp",
+    ]
+
+
+def write_mcp_config(
+    session_dir: Path,
+    *,
+    fmt: str = "generic",
+    path: str | None = None,
+) -> None:
+    """Write the MCP server configuration JSON for the given agent format.
+
+    Supported formats:
+
+    * ``"generic"`` — Claude Code / generic MCP schema at ``.mcp.json``
+    * ``"gemini"`` — Gemini CLI schema at ``.gemini/settings.json``
+    * ``"opencode"`` — OpenCode schema at ``.opencode/opencode.json``
+
+    Args:
+        session_dir: Root of the session workspace; config paths are
+            resolved relative to this directory.
+        fmt: Target config format. Must be one of the supported strings.
+        path: Override the default config file path (relative to
+            ``session_dir``). If omitted the format-specific default is used.
+
+    Raises:
+        ValueError: If ``fmt`` is not a recognised format string.
+    """
+    cmd = _mcp_command()
+
+    if fmt == "generic":
+        default_path = ".mcp.json"
+        config = {
+            "mcpServers": {
+                "studyctl-mcp": {
+                    "command": cmd[0],
+                    "args": cmd[1:],
+                }
+            }
+        }
+    elif fmt == "gemini":
+        default_path = ".gemini/settings.json"
+        config = {
+            "mcpServers": {
+                "studyctl-mcp": {
+                    "command": cmd[0],
+                    "args": cmd[1:],
+                }
+            }
+        }
+    elif fmt == "opencode":
+        default_path = ".opencode/opencode.json"
+        config = {
+            "mcp": {
+                "studyctl-mcp": {
+                    "command": cmd,
+                    "enabled": True,
+                    "type": "local",
+                }
+            }
+        }
+    else:
+        raise ValueError(f"Unknown MCP config format: {fmt!r}")
+
+    target = session_dir / (path or default_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(config, indent=2), encoding="utf-8")

studyctl-2.4.0/src/studyctl/adapters/claude.py

@@ -0,0 +1,36 @@
+"""Claude adapter — persona via --append-system-prompt-file flag.
+
+Claude Code accepts a temp file path via this flag. The file is written
+with 0600 permissions so persona content is not world-readable.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from studyctl.adapters._protocol import AgentAdapter
+from studyctl.adapters._strategies import cli_flag_setup
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _claude_launch(persona_path: Path, resume: bool) -> str:
+    """Build Claude launch command with absolute binary path.
+
+    Resolves to absolute path because tmux panes run non-interactive
+    shells which don't source .zshrc (~/.local/bin not in PATH).
+    """
+    binary = shutil.which("claude") or "claude"
+    if resume:
+        return f"{binary} -r --append-system-prompt-file {persona_path}"
+    return f"{binary} --append-system-prompt-file {persona_path}"
+
+
+ADAPTER = AgentAdapter(
+    name="claude",
+    binary="claude",
+    setup=cli_flag_setup,
+    launch_cmd=_claude_launch,
+)

studyctl-2.4.0/src/studyctl/adapters/gemini.py

@@ -0,0 +1,46 @@
+"""Gemini adapter — persona via GEMINI.md in session CWD.
+
+Gemini CLI auto-loads GEMINI.md from the current working directory
+(3-tier hierarchy: global, workspace, JIT). MCP config goes in
+.gemini/settings.json in the session directory.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from studyctl.adapters._protocol import AgentAdapter
+from studyctl.adapters._strategies import write_mcp_config
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _gemini_setup(canonical_content: str, session_dir: Path) -> Path:
+    """Write GEMINI.md to session dir (auto-loaded by Gemini CLI from cwd)."""
+    persona_path = session_dir / "GEMINI.md"
+    persona_path.write_text(canonical_content)
+    return persona_path
+
+
+def _gemini_launch(_persona_path: Path, resume: bool) -> str:
+    """Build Gemini launch command. Gemini picks up GEMINI.md from cwd."""
+    binary = shutil.which("gemini") or "gemini"
+    if resume:
+        return f"{binary} -r"
+    return binary
+
+
+def _gemini_mcp(session_dir: Path) -> None:
+    """Write .gemini/settings.json with studyctl-mcp server config."""
+    write_mcp_config(session_dir, fmt="gemini")
+
+
+ADAPTER = AgentAdapter(
+    name="gemini",
+    binary="gemini",
+    setup=_gemini_setup,
+    launch_cmd=_gemini_launch,
+    mcp_setup=_gemini_mcp,
+)

studyctl-2.4.0/src/studyctl/adapters/kiro.py

@@ -0,0 +1,113 @@
+"""Kiro adapter — persona via ~/.kiro/agents/study-mentor.json.
+
+Kiro loads agents natively from ~/.kiro/agents/. The setup function
+writes canonical content to a temp persona file, then updates the
+agent JSON's "prompt" field to reference it via file:// URI.
+Teardown restores the original JSON from a backup.
+
+Crash recovery: stale backups are restored on next setup to prevent
+Kiro from permanently using a studyctl-managed prompt.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from studyctl.adapters._protocol import AgentAdapter
+
+logger = logging.getLogger(__name__)
+
+# Repo root: adapters/kiro.py is at
+#   packages/studyctl/src/studyctl/adapters/kiro.py
+# So repo root is six levels up.
+_REPO_ROOT = Path(__file__).parent.parent.parent.parent.parent.parent
+
+KIRO_AGENTS_DIR = Path(os.environ.get("STUDYCTL_KIRO_AGENTS_DIR", Path.home() / ".kiro" / "agents"))
+KIRO_AGENT_NAME = "study-mentor"
+_KIRO_TEMPLATE = _REPO_ROOT / "agents" / "kiro" / "study-mentor.json"
+_KIRO_BACKUP_SUFFIX = ".studyctl-backup"
+
+
+def _kiro_setup(canonical_content: str, _session_dir: Path) -> Path:
+    """Write persona temp file and update Kiro agent JSON atomically."""
+    # 1. Write canonical content to a temp persona file
+    fd, persona_path = tempfile.mkstemp(
+        prefix="studyctl-kiro-persona-",
+        suffix=".md",
+        dir=tempfile.gettempdir(),
+    )
+    os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(canonical_content)
+
+    # 2. Load the base agent template
+    if _KIRO_TEMPLATE.exists():
+        agent_def = json.loads(_KIRO_TEMPLATE.read_text())
+    else:
+        agent_def = {
+            "name": KIRO_AGENT_NAME,
+            "description": "Socratic study mentor",
+        }
+
+    # 3. Update prompt to reference the temp persona file
+    agent_def["prompt"] = f"file://{persona_path}"
+
+    # 4. Ensure target directory exists
+    KIRO_AGENTS_DIR.mkdir(parents=True, exist_ok=True)
+    target = KIRO_AGENTS_DIR / f"{KIRO_AGENT_NAME}.json"
+    backup = target.with_suffix(target.suffix + _KIRO_BACKUP_SUFFIX)
+
+    # 4a. Recover from crash: if a backup exists, the previous session's
+    # teardown never ran. Restore the user's original config first.
+    if backup.exists():
+        logger.warning(
+            "Stale Kiro backup detected (previous session crashed?) — restoring %s",
+            backup,
+        )
+        os.replace(backup, target)
+
+    # 5. Backup existing agent JSON if present
+    if target.exists():
+        shutil.copy2(target, backup)
+
+    # 6. Atomic write: temp file in same dir → os.replace()
+    fd2, tmp_json = tempfile.mkstemp(
+        prefix=f"{KIRO_AGENT_NAME}-",
+        suffix=".json",
+        dir=str(KIRO_AGENTS_DIR),
+    )
+    with os.fdopen(fd2, "w") as f:
+        json.dump(agent_def, f, indent=2)
+    os.replace(tmp_json, target)
+
+    return Path(persona_path)
+
+
+def _kiro_launch(_persona_path: Path, resume: bool) -> str:
+    """Build Kiro launch command."""
+    binary = shutil.which("kiro-cli") or shutil.which("kiro") or "kiro-cli"
+    if resume:
+        return f"{binary} chat --agent {KIRO_AGENT_NAME} --resume"
+    return f"{binary} chat --agent {KIRO_AGENT_NAME}"
+
+
+def _kiro_teardown(_session_dir: Path) -> None:
+    """Restore the backed-up Kiro agent JSON."""
+    target = KIRO_AGENTS_DIR / f"{KIRO_AGENT_NAME}.json"
+    backup = target.with_suffix(target.suffix + _KIRO_BACKUP_SUFFIX)
+    if backup.exists():
+        os.replace(backup, target)
+
+
+ADAPTER = AgentAdapter(
+    name="kiro",
+    binary="kiro-cli",
+    setup=_kiro_setup,
+    launch_cmd=_kiro_launch,
+    teardown=_kiro_teardown,
+)