Skip to content

Self-improving AI Employees for everyone

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__.py
index 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: E402
from ._provider import AnthropicClaudeProvider # noqa: E402
+from ._skills import materialise_skills as _claude_materialise_skills # noqa: E402
register_provider("claude", AnthropicClaudeProvider)
+register_session_pool("claude", _claude_get_session_pool)
+register_skill_materialiser("claude", _claude_materialise_skills)
# Claude Code-supported models. Per
diff --git a/server/services/cli_agent/session_pool.py b/server/nodes/agent/claude_code_agent/_pool.py
similarity index 99%
rename from server/services/cli_agent/session_pool.py
rename to server/nodes/agent/claude_code_agent/_pool.py
index 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_skills
new_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_skills
target_dir = workspace_dir or cwd
await 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.py
index 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.py
similarity index 100%
rename from server/services/cli_agent/_skills.py
rename to server/nodes/agent/claude_code_agent/_skills.py
diff --git a/server/scripts/smoke_test_skills.py b/server/scripts/smoke_test_skills.py
index 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.parent
sys.path.insert(0, str(server_dir))
- from services.cli_agent._skills import materialise_skills
- from services.cli_agent.session_pool import get_session_pool
from services.cli_agent.types import ClaudeTaskSpec
from 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_skills
repo_root = server_dir.parent
memory_node_id = "smoke-test-memory"
diff --git a/server/services/cli_agent/factory.py b/server/services/cli_agent/factory.py
index 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, Union
from 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.py
index 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``: claude
mints a fresh UUID and starts writing to
``<project_key>/<new_uuid>.jsonl``; the watcher fires the callback
diff --git a/server/services/cli_agent/service.py b/server/services/cli_agent/service.py
index 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_pool
if 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.py
index 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.py
index 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 wired
through 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` which
writes the connected SKILL.md trees under
``<cwd>/.claude/skills/`` before spawn so the built-in skill
loader has something to discover.