Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(cli_agent): Phase 2 — move session pool + skill materialiser into plugin folder
trohitg6dcf358f804a
diff --git a/server/nodes/agent/claude_code_agent/__init__.py b/server/nodes/agent/claude_code_agent/__init__.pyindex 66b7658c..98bfcbc1 100644--- a/server/nodes/agent/claude_code_agent/__init__.py+++ b/server/nodes/agent/claude_code_agent/__init__.py@@ -43,12 +43,21 @@ from services.cli_agent.types import SessionResultModel # noqa: E402# ``docs-internal/plugin_system.md`` § "Self-contained plugin folders"),# the plugin folder owns its provider class + auth helpers + session# pool + skill materialiser. The generic framework-# (``services/cli_agent/``) doesn't import from us — it asks the-# ``register_provider`` registry for the provider class by name.-from services.cli_agent.factory import register_provider # noqa: E402+# (``services/cli_agent/``) doesn't import from us — it asks three+# parallel registries (one per concern, all in ``factory.py``) for+# the right callable by provider name.+from services.cli_agent.factory import ( # noqa: E402+ register_provider,+ register_session_pool,+ register_skill_materialiser,+)+from ._pool import get_session_pool as _claude_get_session_pool # noqa: E402from ._provider import AnthropicClaudeProvider # noqa: E402+from ._skills import materialise_skills as _claude_materialise_skills # noqa: E402register_provider("claude", AnthropicClaudeProvider)+register_session_pool("claude", _claude_get_session_pool)+register_skill_materialiser("claude", _claude_materialise_skills)# Claude Code-supported models. Perdiff --git a/server/services/cli_agent/session_pool.py b/server/nodes/agent/claude_code_agent/_pool.pysimilarity index 99%rename from server/services/cli_agent/session_pool.pyrename to server/nodes/agent/claude_code_agent/_pool.pyindex 7519cca6..b6534756 100644--- a/server/services/cli_agent/session_pool.py+++ b/server/nodes/agent/claude_code_agent/_pool.py@@ -141,7 +141,7 @@ class PooledClaudeSession:workspace_dir: Optional[Path] = None# Set of skill names currently materialised under# ``<workspace_dir>/.claude/skills/`` for this warm subprocess.- # The pool calls :func:`services.cli_agent._skills.materialise_skills`+ # The pool calls :func:`nodes.agent.claude_code_agent._skills.materialise_skills`# with this as the ``previous_skill_names`` arg on every warm# reuse, so only the delta is touched on disk. Claude's filesystem# watcher picks up add/remove events without respawning.@@ -304,7 +304,7 @@ class ClaudeSessionPool:# ``existing.materialised_skills`` and only touches# the delta on disk.if existing.workspace_dir is not None:- from services.cli_agent._skills import materialise_skills+ from ._skills import materialise_skillsnew_set = frozenset(connected_skill_names or [])added, removed = await materialise_skills(existing.workspace_dir,@@ -572,7 +572,7 @@ class ClaudeSessionPool:# Falls back to ``cwd`` only when no workspace_dir was# provided (defensive — every production caller passes one).if connected_skill_names:- from services.cli_agent._skills import materialise_skills+ from ._skills import materialise_skillstarget_dir = workspace_dir or cwdawait materialise_skills(target_dir, connected_skill_names,diff --git a/server/nodes/agent/claude_code_agent/_provider.py b/server/nodes/agent/claude_code_agent/_provider.pyindex eb23aabd..9babfc56 100644--- a/server/nodes/agent/claude_code_agent/_provider.py+++ b/server/nodes/agent/claude_code_agent/_provider.py@@ -19,7 +19,7 @@ Subprocess: ``claude --permission-mode bypassPermissions- ``--allowedTools`` carries the explicit allowlist (built-ins +every wired MCP tool) — same shape as the prior headless path.- Skills are materialised under ``<cwd>/.claude/skills/`` by the- shared :func:`services.cli_agent._skills.materialise_skills`+ shared :func:`nodes.agent.claude_code_agent._skills.materialise_skills`helper (called from both ``AICliSession._pre_spawn`` AND``ClaudeSessionPool._spawn``); ``Skill`` enters``--allowedTools`` iff at least one skill is wired.@@ -270,7 +270,7 @@ class AnthropicClaudeProvider:# when at least one skill is wired through ``input-skill``.# The spawn path (pool + non-pool) materialises connected# SKILL.md files under ``<cwd>/.claude/skills/`` via the- # shared :func:`services.cli_agent._skills.materialise_skills`+ # shared :func:`nodes.agent.claude_code_agent._skills.materialise_skills`# helper, so the built-in skill loader has something to# discover. Skills accessed by name (`Skill <name>`) load# those materialised files. If no skill is wired, ``Skill``diff --git a/server/services/cli_agent/_skills.py b/server/nodes/agent/claude_code_agent/_skills.pysimilarity index 100%rename from server/services/cli_agent/_skills.pyrename to server/nodes/agent/claude_code_agent/_skills.pydiff --git a/server/scripts/smoke_test_skills.py b/server/scripts/smoke_test_skills.pyindex 0774204c..81e8e5a3 100644--- a/server/scripts/smoke_test_skills.py+++ b/server/scripts/smoke_test_skills.py@@ -39,10 +39,10 @@ async def main() -> int:server_dir = Path(__file__).resolve().parent.parentsys.path.insert(0, str(server_dir))- from services.cli_agent._skills import materialise_skills- from services.cli_agent.session_pool import get_session_poolfrom services.cli_agent.types import ClaudeTaskSpecfrom nodes.agent.claude_code_agent._oauth import MACHINA_CLAUDE_DIR+ from nodes.agent.claude_code_agent._pool import get_session_pool+ from nodes.agent.claude_code_agent._skills import materialise_skillsrepo_root = server_dir.parentmemory_node_id = "smoke-test-memory"diff --git a/server/services/cli_agent/factory.py b/server/services/cli_agent/factory.pyindex 7222d582..3584ae60 100644--- a/server/services/cli_agent/factory.py+++ b/server/services/cli_agent/factory.py@@ -23,7 +23,7 @@ Usage from a plugin's ``__init__.py``::from __future__ import annotations-from typing import Callable, Dict, Type, Union+from typing import Any, Callable, Dict, Optional, Type, Unionfrom core.logging import get_logger@@ -38,6 +38,25 @@ logger = get_logger(__name__)# ``AICliProvider``-conformant instance._PROVIDER_REGISTRY: Dict[str, Union[Type[AICliProvider], Callable[[], AICliProvider]]] = {}+# Per-provider session pool factories. Pool implementations are+# provider-specific (claude uses subprocess + stream-json pooling; codex+# / gemini don't) and live in the plugin folder per the canonical+# layout. This registry lets the framework's pool dispatcher+# (``service.py::_run_pooled_turn``) look up the right pool by+# provider name without importing from the plugin folder directly.+_POOL_REGISTRY: Dict[str, Callable[[], Any]] = {}++# Per-provider skill materialisers. Only claude implements one today —+# it writes ``SKILL.md`` trees under ``<workspace>/.claude/skills/``+# per the Anthropic Skills spec (code.claude.com/docs/en/skills).+# Codex / Gemini don't honor SKILL.md so they don't register here.+# The framework's session bootstrap (``session.py:_pre_spawn``)+# looks up by provider name; ``None`` means no-op (skip materialise).+#+# Signature: ``async (workspace_dir, skill_names, *, previous_skill_names,+# log_label) -> tuple[int, int]`` — (added_count, removed_count).+_SKILL_MATERIALISER_REGISTRY: Dict[str, Callable[..., Any]] = {}+def register_provider(name: str,@@ -102,3 +121,79 @@ def is_supported(name: str) -> bool:def registered_provider_names() -> frozenset[str]:"""Frozen snapshot of currently-registered provider names."""return frozenset(_PROVIDER_REGISTRY.keys())+++# ---------------------------------------------------------------------------+# Session-pool registry — paired with provider registry above+# ---------------------------------------------------------------------------++def register_session_pool(+ provider_name: str,+ pool_getter: Callable[[], Any],+) -> None:+ """Bind a provider to a callable returning its session pool singleton.++ Called from the plugin folder's ``__init__.py`` on import. The+ pool object must expose ``acquire``, ``send_turn``, ``release``,+ ``clear``, ``terminate``, ``shutdown_all``, and ``start_reaper`` —+ the surface ``services.cli_agent.service._run_pooled_turn`` uses.++ Idempotent on identical binding; raises ``ValueError`` on conflict+ so accidental double-registration with different getters is caught.+ """+ existing = _POOL_REGISTRY.get(provider_name)+ if existing is not None and existing is not pool_getter:+ raise ValueError(+ f"Session pool for {provider_name!r} already registered "+ f"({existing!r}); refusing to overwrite with {pool_getter!r}"+ )+ _POOL_REGISTRY[provider_name] = pool_getter+ logger.debug(+ "[cli_agent] registered session pool %r -> %r",+ provider_name, pool_getter,+ )+++def get_session_pool(provider_name: str) -> Optional[Any]:+ """Return the session pool singleton for ``provider_name`` or ``None``.++ Calls the registered getter (provider-side) so the pool is lazily+ instantiated on first request.+ """+ getter = _POOL_REGISTRY.get(provider_name)+ if getter is None:+ return None+ return getter()+++# ---------------------------------------------------------------------------+# Skill-materialiser registry+# ---------------------------------------------------------------------------++def register_skill_materialiser(+ provider_name: str,+ materialiser: Callable[..., Any],+) -> None:+ """Bind a provider to its skill materialiser (claude only today).++ Called from the plugin folder's ``__init__.py`` on import. The+ materialiser must be an async callable with signature+ ``(workspace_dir, skill_names, *, previous_skill_names, log_label)+ -> tuple[int, int]`` (added_count, removed_count).+ """+ existing = _SKILL_MATERIALISER_REGISTRY.get(provider_name)+ if existing is not None and existing is not materialiser:+ raise ValueError(+ f"Skill materialiser for {provider_name!r} already registered "+ f"({existing!r}); refusing to overwrite with {materialiser!r}"+ )+ _SKILL_MATERIALISER_REGISTRY[provider_name] = materialiser+ logger.debug(+ "[cli_agent] registered skill materialiser %r -> %r",+ provider_name, materialiser,+ )+++def get_skill_materialiser(provider_name: str) -> Optional[Callable[..., Any]]:+ """Return the registered materialiser or ``None`` (= skip materialise)."""+ return _SKILL_MATERIALISER_REGISTRY.get(provider_name)diff --git a/server/services/cli_agent/jsonl_watcher.py b/server/services/cli_agent/jsonl_watcher.pyindex bb129ec5..09723ecb 100644--- a/server/services/cli_agent/jsonl_watcher.py+++ b/server/services/cli_agent/jsonl_watcher.py@@ -200,7 +200,7 @@ class JsonlWatcher:class JsonlDirWatcher:"""Watch a directory for newly-appearing ``.jsonl`` files.- Used by :class:`services.cli_agent.session_pool.ClaudeSessionPool`+ Used by :class:`nodes.agent.claude_code_agent._pool.ClaudeSessionPool`to capture the new session UUID after sending ``/clear``: claudemints a fresh UUID and starts writing to``<project_key>/<new_uuid>.jsonl``; the watcher fires the callbackdiff --git a/server/services/cli_agent/service.py b/server/services/cli_agent/service.pyindex d451cfbc..bbbde35d 100644--- a/server/services/cli_agent/service.py+++ b/server/services/cli_agent/service.py@@ -405,8 +405,14 @@ class AICliService:``/clear`` rotation and new-UUID capture happen inside the pool.The MCP bearer token stays with the spawned claude across batches— see the use-pool branch in :meth:`run_batch` for the rationale.++ The pool lives in the plugin folder (per the canonical+ plugin-folder layout); we look it up through the+ :func:`services.cli_agent.factory.get_session_pool` registry+ instead of importing directly so the framework stays free of+ any ``services → nodes`` layering violation."""- from services.cli_agent.session_pool import get_session_pool+ from services.cli_agent.factory import get_session_poolif not isinstance(task, ClaudeTaskSpec):raise TypeError(@@ -414,7 +420,14 @@ class AICliService:f"{type(task).__name__}")- pool = get_session_pool()+ pool = get_session_pool("claude")+ if pool is None:+ raise RuntimeError(+ "No session pool registered for 'claude'. The "+ "claude_code_agent plugin's __init__.py should call "+ "register_session_pool('claude', get_session_pool). "+ "Did its module fail to import?"+ )await pool.start_reaper()mcp_endpoint_url = (diff --git a/server/services/cli_agent/session.py b/server/services/cli_agent/session.pyindex dd668165..4b7377e8 100644--- a/server/services/cli_agent/session.py+++ b/server/services/cli_agent/session.py@@ -273,17 +273,23 @@ class AICliSession(BaseProcessSupervisor):# when both share ``cwd=repo_root``. Claude discovers them# via ``--add-dir <workspace_dir>`` (emitted in argv) per the# skills spec's "Automatic discovery from parent and nested- # directories" rule. Same helper now also runs on the pool- # path so memory-bound runs get the built-in ``Skill`` tool- # too.+ # directories" rule.+ #+ # The materialiser is provider-specific (only claude honours+ # SKILL.md per the Anthropic Skills spec); we look it up+ # through ``factory.get_skill_materialiser`` so the framework+ # stays decoupled from the plugin's implementation. Codex /+ # Gemini don't register one → call is a no-op.if self._connected_skill_names:- from services.cli_agent._skills import materialise_skills- await materialise_skills(- self._workspace_dir,- self._connected_skill_names,- previous_skill_names=None,- log_label=self.label,- )+ from services.cli_agent.factory import get_skill_materialiser+ materialiser = get_skill_materialiser(self._provider.name)+ if materialiser is not None:+ await materialiser(+ self._workspace_dir,+ self._connected_skill_names,+ previous_skill_names=None,+ log_label=self.label,+ )# ------------------------------------------------------------------# _do_start: PTY spawn + JSONL watcher (interactive cutover)diff --git a/server/tests/services/cli_agent/test_providers.py b/server/tests/services/cli_agent/test_providers.pyindex 5d6850a5..d699c04e 100644--- a/server/tests/services/cli_agent/test_providers.py+++ b/server/tests/services/cli_agent/test_providers.py@@ -150,7 +150,7 @@ class TestClaudeArgv:"""``Skill`` is the one claude built-in we conditionally allow— present in ``--allowedTools`` iff at least one skill is wiredthrough the agent's ``input-skill`` handle. Paired with- :func:`services.cli_agent._skills.materialise_skills` which+ :func:`nodes.agent.claude_code_agent._skills.materialise_skills` whichwrites the connected SKILL.md trees under``<cwd>/.claude/skills/`` before spawn so the built-in skillloader has something to discover.