forked from molecule-ai/molecule-core
24fec62d7f
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
105 lines
3.7 KiB
Python
105 lines
3.7 KiB
Python
"""Protocol + context types for per-runtime plugin adaptors.
|
|
|
|
Each plugin ships (or has registered for it) a per-runtime adaptor implementing
|
|
``PluginAdaptor``. The platform resolves the adaptor for ``(plugin_name, runtime)``
|
|
via :func:`plugins_registry.resolve` and calls ``install(ctx)`` to wire the
|
|
plugin into a workspace.
|
|
|
|
The :class:`InstallContext` deliberately gives adaptors ONLY the hooks they
|
|
need (``register_tool``, ``register_subagent``, ``append_to_memory``) — it
|
|
does not leak runtime internals. This keeps adaptors thin and lets the
|
|
workspace runtime adapter (claude_code, deepagents, …) own its own state.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from dataclasses import dataclass, field
|
|
from pathlib import Path
|
|
from typing import Any, Callable, Protocol, runtime_checkable
|
|
|
|
|
|
# Default filename for the runtime's long-lived memory file. Claude Code
|
|
# and DeepAgents both read CLAUDE.md natively; other runtimes override via
|
|
# BaseAdapter.memory_filename() and that value flows through
|
|
# InstallContext.memory_filename so adaptors don't hardcode the name.
|
|
DEFAULT_MEMORY_FILENAME = "CLAUDE.md"
|
|
|
|
# Subdirectory under /configs where skills get installed.
|
|
SKILLS_SUBDIR = "skills"
|
|
|
|
|
|
@dataclass
|
|
class InstallContext:
|
|
"""Hooks + state passed to every PluginAdaptor.install() call.
|
|
|
|
Adaptors should treat unknown verbs as no-ops on runtimes that don't
|
|
support them (e.g. ``register_subagent`` is a no-op on Claude Code).
|
|
"""
|
|
|
|
configs_dir: Path
|
|
"""Workspace's /configs directory (where CLAUDE.md, plugins/, skills/ live)."""
|
|
|
|
workspace_id: str
|
|
"""Workspace UUID — useful for per-workspace state or logging."""
|
|
|
|
runtime: str
|
|
"""Runtime identifier (``claude_code``, ``deepagents``, …)."""
|
|
|
|
plugin_root: Path
|
|
"""Path to the plugin's directory (where plugin.yaml + content lives)."""
|
|
|
|
memory_filename: str = DEFAULT_MEMORY_FILENAME
|
|
"""Runtime's long-lived memory file (populated from
|
|
:meth:`BaseAdapter.memory_filename`). Adaptors pass this to
|
|
:attr:`append_to_memory` instead of hardcoding a filename so runtimes
|
|
with non-standard memory files (e.g. ``AGENTS.md``) work unchanged."""
|
|
|
|
register_tool: Callable[[str, Callable[..., Any]], None] = field(
|
|
default=lambda name, fn: None
|
|
)
|
|
"""Register a callable as a runtime tool. No-op on runtimes without a
|
|
dynamic tool registry — those runtimes pick tools up at startup via
|
|
filesystem scan instead."""
|
|
|
|
register_subagent: Callable[[str, dict[str, Any]], None] = field(
|
|
default=lambda name, spec: None
|
|
)
|
|
"""Register a sub-agent specification (DeepAgents-only). No-op elsewhere."""
|
|
|
|
append_to_memory: Callable[[str, str], None] = field(
|
|
default=lambda filename, content: None
|
|
)
|
|
"""Append text to a runtime memory file (e.g. CLAUDE.md). The default
|
|
no-op lets adaptors run in test harnesses that don't have a real
|
|
workspace filesystem."""
|
|
|
|
logger: logging.Logger = field(default_factory=lambda: logging.getLogger(__name__))
|
|
|
|
|
|
@dataclass
|
|
class InstallResult:
|
|
"""Outcome of a PluginAdaptor.install() call."""
|
|
|
|
plugin_name: str
|
|
runtime: str
|
|
source: str # "registry" | "plugin" | "raw_drop"
|
|
files_written: list[str] = field(default_factory=list)
|
|
tools_registered: list[str] = field(default_factory=list)
|
|
subagents_registered: list[str] = field(default_factory=list)
|
|
warnings: list[str] = field(default_factory=list)
|
|
|
|
|
|
@runtime_checkable
|
|
class PluginAdaptor(Protocol):
|
|
"""Contract every per-runtime adaptor must implement."""
|
|
|
|
plugin_name: str
|
|
runtime: str
|
|
|
|
async def install(self, ctx: InstallContext) -> InstallResult:
|
|
...
|
|
|
|
async def uninstall(self, ctx: InstallContext) -> None:
|
|
...
|