superpos-agent-core 0.1.0__tar.gz

superpos_agent_core-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: superpos-agent-core
+Version: 0.1.0
+Summary: Shared runtime for Superpos slim agents (Telegram bot, Superpos poller, worktree manager, telegram streamer).
+Author: Superpos
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# superpos-agent-core
+
+Shared runtime for the Superpos "slim agent" family — the part that is identical across Claude, Codex, Gemini, Qwen, and any future LLM-CLI-backed agent.
+
+## What lives here
+
+- `Executor` protocol + `ExecutionRequest` — the contract every agent implementation must satisfy.
+- `SuperposClient` — REST client for the Superpos backend (tasks, persona, agent lifecycle).
+- `run_superpos_poller` — daemon that polls Superpos for tasks and enqueues them on an `Executor`.
+- `TelegramGateway` + `TelegramStreamer` + `build_telegram_app` / `run_telegram_bot` — Telegram I/O with backpressure, flood-ban handling, message streaming.
+- `WorktreeManager` helpers — per-branch isolation via `git worktree`.
+- `SessionStore`, `RecentTasksLog`, `RuntimeConfig` — persistence and runtime knobs.
+- `redact()` — strip known secret patterns from outbound text.
+- `run_agent()` — orchestrator that wires everything together given a concrete `Executor` factory.
+
+## What does NOT live here
+
+- Per-agent executor implementations (`ClaudeExecutor`, `CodexExecutor`, `GeminiExecutor`, …) — they live in each agent's own repo and depend on this package.
+- LLM SDK / CLI installation — each agent's Dockerfile is responsible.
+- Per-agent config (model lists, auth env vars) — subclassed from `BaseConfig`.
+
+## Using it
+
+```python
+from superpos_agent_core import run_agent, BaseConfig, Executor
+
+class MyAgentConfig(BaseConfig):
+    my_api_key: str = ""
+
+class MyExecutor:
+    # implements superpos_agent_core.Executor
+    ...
+
+if __name__ == "__main__":
+    import asyncio
+    config = MyAgentConfig.from_env(extra={"my_api_key": "MY_API_KEY"})
+    asyncio.run(run_agent(
+        config=config,
+        executor_factory=lambda cfg, runtime, superpos, gateway, persona:
+            MyExecutor(cfg, runtime, superpos, gateway, persona=persona),
+    ))
+```
+
+See `Slim-Agent-Gemini/` for a complete working example.

superpos_agent_core-0.1.0/README.md

@@ -0,0 +1,44 @@
+# superpos-agent-core
+
+Shared runtime for the Superpos "slim agent" family — the part that is identical across Claude, Codex, Gemini, Qwen, and any future LLM-CLI-backed agent.
+
+## What lives here
+
+- `Executor` protocol + `ExecutionRequest` — the contract every agent implementation must satisfy.
+- `SuperposClient` — REST client for the Superpos backend (tasks, persona, agent lifecycle).
+- `run_superpos_poller` — daemon that polls Superpos for tasks and enqueues them on an `Executor`.
+- `TelegramGateway` + `TelegramStreamer` + `build_telegram_app` / `run_telegram_bot` — Telegram I/O with backpressure, flood-ban handling, message streaming.
+- `WorktreeManager` helpers — per-branch isolation via `git worktree`.
+- `SessionStore`, `RecentTasksLog`, `RuntimeConfig` — persistence and runtime knobs.
+- `redact()` — strip known secret patterns from outbound text.
+- `run_agent()` — orchestrator that wires everything together given a concrete `Executor` factory.
+
+## What does NOT live here
+
+- Per-agent executor implementations (`ClaudeExecutor`, `CodexExecutor`, `GeminiExecutor`, …) — they live in each agent's own repo and depend on this package.
+- LLM SDK / CLI installation — each agent's Dockerfile is responsible.
+- Per-agent config (model lists, auth env vars) — subclassed from `BaseConfig`.
+
+## Using it
+
+```python
+from superpos_agent_core import run_agent, BaseConfig, Executor
+
+class MyAgentConfig(BaseConfig):
+    my_api_key: str = ""
+
+class MyExecutor:
+    # implements superpos_agent_core.Executor
+    ...
+
+if __name__ == "__main__":
+    import asyncio
+    config = MyAgentConfig.from_env(extra={"my_api_key": "MY_API_KEY"})
+    asyncio.run(run_agent(
+        config=config,
+        executor_factory=lambda cfg, runtime, superpos, gateway, persona:
+            MyExecutor(cfg, runtime, superpos, gateway, persona=persona),
+    ))
+```
+
+See `Slim-Agent-Gemini/` for a complete working example.

superpos_agent_core-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "superpos-agent-core"
+version = "0.1.0"
+description = "Shared runtime for Superpos slim agents (Telegram bot, Superpos poller, worktree manager, telegram streamer)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Superpos" }]
+dependencies = [
+    "python-telegram-bot>=21.0",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+superpos_agent_core = [
+    "py.typed",
+    "modules/**/*.yaml",
+    "modules/**/*.md",
+    "modules/**/scripts/*",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["F401"]

superpos_agent_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

superpos_agent_core-0.1.0/src/superpos_agent_core/__init__.py

@@ -0,0 +1,67 @@
+"""Slim-agent core runtime: shared code for every Superpos LLM-backed agent."""
+
+from .config import BaseConfig
+from .executor import Executor, ExecutionRequest
+from .main import ExecutorFactory, run_agent, setup_logging
+from .module_loader import (
+    bundled_modules_dir,
+    collect_mcp_servers,
+    discover_modules,
+    generate_modules_doc,
+)
+from .module_setup import run_setup as run_module_setup
+from .module_setup import symlink_module_scripts
+from .sub_agent_sync import sync_sub_agents
+from .progress_reporter import report_progress
+from .recent_tasks import RecentTasksLog, TaskSummary
+from .redactor import redact
+from .runtime_config import RuntimeConfig
+from .session_store import SessionStore
+from .superpos_client import SuperposClient
+from .superpos_poller import run_superpos_poller
+from .telegram_bot import build_telegram_app, run_telegram_bot
+from .telegram_gateway import Priority, TelegramGateway
+from .telegram_streamer import TelegramStreamer
+from .worktree_manager import (
+    ensure_worktree,
+    infer_branch,
+    is_git_repo,
+    prune_worktrees,
+    slot_key,
+    worktree_path,
+)
+
+__all__ = [
+    "BaseConfig",
+    "Executor",
+    "ExecutionRequest",
+    "ExecutorFactory",
+    "Priority",
+    "RecentTasksLog",
+    "RuntimeConfig",
+    "SessionStore",
+    "SuperposClient",
+    "TaskSummary",
+    "TelegramGateway",
+    "TelegramStreamer",
+    "build_telegram_app",
+    "bundled_modules_dir",
+    "collect_mcp_servers",
+    "discover_modules",
+    "ensure_worktree",
+    "generate_modules_doc",
+    "infer_branch",
+    "is_git_repo",
+    "prune_worktrees",
+    "redact",
+    "report_progress",
+    "run_agent",
+    "run_module_setup",
+    "run_superpos_poller",
+    "run_telegram_bot",
+    "setup_logging",
+    "slot_key",
+    "sync_sub_agents",
+    "symlink_module_scripts",
+    "worktree_path",
+]

superpos_agent_core-0.1.0/src/superpos_agent_core/config.py

@@ -0,0 +1,157 @@
+"""Base configuration shared across every slim agent.
+
+Each per-agent package defines its own subclass adding LLM-specific fields
+(model id, API key env var name, reasoning effort, …).  Superpos and Telegram
+fields are universal and live here.
+
+Fields are seeded from env at startup and may be mutated at runtime when the
+Superpos ``/agents/me`` endpoint returns server-authoritative values for
+``hive_id``, ``capabilities``, ``permissions``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BaseConfig:
+    """Universal slim-agent config.  Subclass to add per-agent fields."""
+
+    # ── Superpos ──────────────────────────────────────────────────────
+    superpos_base_url: str = ""
+    superpos_hive_id: str = ""
+    superpos_agent_id: str = ""
+    superpos_api_token: str = ""
+    superpos_refresh_token: str = ""
+    superpos_capabilities: list[str] = field(default_factory=list)
+    superpos_permissions: list[str] = field(default_factory=list)
+    superpos_poll_interval: int = 5
+
+    # Knowledge retrieval injection: before dispatching a Superpos task, search
+    # the hive knowledge store for entries relevant to the task and prepend them
+    # to the prompt so the agent always starts with the hive's memory in context
+    # (instead of only seeing it if it happens to call the knowledge CLI).
+    superpos_knowledge_inject: bool = True
+    superpos_knowledge_inject_limit: int = 5
+
+    # ── Telegram ──────────────────────────────────────────────────────
+    telegram_bot_token: str = ""
+    telegram_allowed_users: list[int] = field(default_factory=list)
+    telegram_chat_id: str = ""
+
+    # ── Executor (LLM-agnostic) ───────────────────────────────────────
+    executor_kind: str = "generic"  # subclasses set this: "claude", "codex", "gemini", …
+    executor_working_dir: str = "/workspace"
+    executor_worktree_isolation: bool = False
+    executor_max_parallel: int = 3
+    executor_max_turns: int = 30
+
+    # Filesystem layout — where this agent stores per-LLM session/config state.
+    # Defaults to /home/agent/.<executor_kind> at runtime in __post_init__.
+    home_dir: str = ""
+
+    # Voice transcription (optional — only used if Telegram receives voice notes).
+    # Whisper API is the default; OpenAI API key may already be set for other
+    # reasons (Codex), but Claude/Gemini agents can set this independently.
+    voice_transcribe_api_key: str = ""
+
+    # Module discovery root.  Agents that don't ship modules can leave blank.
+    modules_dir: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.home_dir:
+            home = os.environ.get("HOME", "/home/agent")
+            self.home_dir = os.path.join(home, f".{self.executor_kind}")
+        if not self.modules_dir:
+            self.modules_dir = os.path.join(
+                self.executor_working_dir, f".{self.executor_kind}", "modules"
+            )
+
+    # ── Base env loader.  Subclasses call super().from_env() and extend. ──
+
+    @classmethod
+    def _base_env_kwargs(cls) -> dict:
+        """Pull universal fields from env vars.  Subclasses extend this."""
+        allowed = os.environ.get("TELEGRAM_ALLOWED_USERS", "")
+        caps = os.environ.get("SUPERPOS_CAPABILITIES", "")
+        working_dir = os.environ.get("EXECUTOR_WORKING_DIR") or os.environ.get(
+            "WORKING_DIR", "/workspace"
+        )
+
+        isolation_env = os.environ.get("EXECUTOR_WORKTREE_ISOLATION") or os.environ.get(
+            "WORKTREE_ISOLATION"
+        )
+        if isolation_env is not None:
+            worktree_isolation = isolation_env.lower() not in ("0", "false", "no")
+        else:
+            # Auto-enable when the working directory is a git repo
+            worktree_isolation = os.path.isdir(os.path.join(working_dir, ".git"))
+
+        return dict(
+            superpos_base_url=os.environ.get("SUPERPOS_BASE_URL", ""),
+            superpos_hive_id=os.environ.get("SUPERPOS_HIVE_ID", ""),
+            superpos_agent_id=os.environ.get("SUPERPOS_AGENT_ID", ""),
+            superpos_api_token=os.environ.get("SUPERPOS_API_TOKEN", ""),
+            superpos_refresh_token=os.environ.get("SUPERPOS_REFRESH_TOKEN", ""),
+            superpos_capabilities=[c.strip() for c in caps.split(",") if c.strip()],
+            superpos_poll_interval=int(os.environ.get("SUPERPOS_POLL_INTERVAL", "5")),
+            superpos_knowledge_inject=os.environ.get(
+                "SUPERPOS_KNOWLEDGE_INJECT", "true"
+            ).lower()
+            not in ("0", "false", "no"),
+            superpos_knowledge_inject_limit=int(
+                os.environ.get("SUPERPOS_KNOWLEDGE_INJECT_LIMIT", "5")
+            ),
+            telegram_bot_token=os.environ.get("TELEGRAM_BOT_TOKEN", ""),
+            telegram_allowed_users=[
+                int(u.strip()) for u in allowed.split(",") if u.strip()
+            ],
+            telegram_chat_id=os.environ.get("TELEGRAM_CHAT_ID", ""),
+            executor_working_dir=working_dir,
+            executor_worktree_isolation=worktree_isolation,
+            executor_max_parallel=int(os.environ.get("EXECUTOR_MAX_PARALLEL", "3")),
+            executor_max_turns=int(os.environ.get("EXECUTOR_MAX_TURNS", "30")),
+            voice_transcribe_api_key=os.environ.get("VOICE_TRANSCRIBE_API_KEY", "")
+            or os.environ.get("OPENAI_API_KEY", ""),
+        )
+
+    @classmethod
+    def from_env(cls) -> "BaseConfig":
+        return cls(**cls._base_env_kwargs())
+
+    # ── Properties ────────────────────────────────────────────────────
+
+    @property
+    def superpos_enabled(self) -> bool:
+        return bool(
+            self.superpos_base_url
+            and self.superpos_hive_id
+            and self.superpos_agent_id
+            and self.superpos_api_token
+        )
+
+    @property
+    def telegram_enabled(self) -> bool:
+        return bool(self.telegram_bot_token)
+
+    def has_permission(self, permission: str) -> bool:
+        """Check whether the agent has a given permission.
+
+        Matches exact, ``category:*`` wildcards, and the ``admin:*``
+        superwildcard.  If permissions are empty (unknown — /me failed
+        and env doesn't carry them), returns True so the agent tries the
+        call; the server will reject if it truly lacks the right.
+        """
+        if not self.superpos_permissions:
+            return True
+        if permission in self.superpos_permissions:
+            return True
+        if "admin:*" in self.superpos_permissions:
+            return True
+        if ":" in permission:
+            category = permission.split(":", 1)[0]
+            if f"{category}:*" in self.superpos_permissions:
+                return True
+        return False

superpos_agent_core-0.1.0/src/superpos_agent_core/executor.py

@@ -0,0 +1,174 @@
+"""Executor contract — the seam between core and per-agent implementations.
+
+Every concrete agent (Claude, Codex, Gemini, Qwen, …) ships a subclass of
+:class:`Executor` that knows how to drive its specific LLM CLI/SDK.  Core
+modules (``superpos_poller``, ``telegram_bot``, ``telegram_streamer``) only
+interact with the abstract surface defined here, so adding a new agent
+means writing one executor — not re-porting the rest of the runtime.
+"""
+
+from __future__ import annotations
+
+import abc
+import asyncio
+from dataclasses import dataclass
+
+
+@dataclass
+class ExecutionRequest:
+    """A single unit of work routed through the executor queue."""
+
+    prompt: str
+    chat_id: int | str
+    source: str  # "telegram" | "superpos"
+    superpos_task_id: str | None = None
+    branch: str | None = None
+    image_paths: list[str] | None = None
+
+
+class Executor(abc.ABC):
+    """Abstract base for per-agent LLM executors.
+
+    Subclasses MUST call ``super().__init__(max_parallel=…)`` so the queue,
+    in-flight set, and active counter are initialized.  Subclasses then
+    own the consumer loop (``run``) and the actual LLM invocation.
+    """
+
+    def __init__(self, max_parallel: int = 1) -> None:
+        self.queue: asyncio.Queue[ExecutionRequest] = asyncio.Queue()
+        self._in_flight_superpos_tasks: set[str] = set()
+        self._max_parallel = max_parallel
+        self._active_count = 0
+        # Per-chat asyncio.Task tracking for /stop.  Subclasses call
+        # ``_track_chat_task`` once they have the running task in hand;
+        # ``cancel_chat`` walks this map.  Keyed by ``str(chat_id)`` so
+        # int/str keys interop with Telegram's int chat_ids and Superpos's
+        # string ones.
+        self._chat_tasks: dict[str, set[asyncio.Task]] = {}
+
+    # ── Abstract: must be implemented per agent ────────────────────────
+
+    @abc.abstractmethod
+    async def run(self) -> None:
+        """Consume the queue forever, dispatching requests to the LLM."""
+
+    @abc.abstractmethod
+    def update_persona(self, prompt: str | None, version: int | None = None) -> None:
+        """Replace the agent's persona/system prompt.
+
+        ``version`` is informational — agents that track persona versions
+        (Claude) can persist it; agents that don't (Codex, Gemini) may ignore.
+        """
+
+    @abc.abstractmethod
+    def clear_session(self, chat_id: int | str) -> None:
+        """Drop any cached conversation state for this chat."""
+
+    # ── Optional: default implementations agents can override ──────────
+
+    async def preflight(self) -> None:
+        """Verify auth/CLI installation before starting the main loop.
+
+        Default no-op.  Agents should override to fail fast on bad creds.
+        """
+        return None
+
+    async def run_background(
+        self,
+        task_id: str,
+        prompt: str,
+        task_type: str = "dream",
+        timeout_seconds: int = 300,
+    ) -> None:
+        """Fire-and-forget execution for housekeeping tasks (dream, knowledge_fillin).
+
+        Default raises NotImplementedError — agents that want background work
+        must override.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} does not implement background tasks"
+        )
+
+    def cleanup_stale_sessions(self, max_age_hours: int = 24) -> dict[str, int]:
+        """Delete LLM-specific stale session artifacts; return stats.
+
+        Returned dict should contain (at minimum) keys: ``projects``,
+        ``session_env``, ``bytes_freed``.  Default returns zeros so the
+        ``/cleanup`` Telegram command works on agents without a
+        per-session disk footprint.
+        """
+        return {"projects": 0, "session_env": 0, "bytes_freed": 0}
+
+    # ── Concrete: shared bookkeeping ───────────────────────────────────
+
+    @property
+    def pending(self) -> int:
+        return self.queue.qsize()
+
+    @property
+    def is_busy(self) -> bool:
+        return self._active_count > 0
+
+    @property
+    def has_free_slots(self) -> bool:
+        """True if more concurrent work can be accepted.
+
+        Uses the in-flight task set rather than ``qsize()`` / ``_active_count``
+        because a task can be claimed but waiting for the semaphore —
+        ``qsize()`` is 0 then, but the slot is taken.
+        """
+        return len(self._in_flight_superpos_tasks) < self._max_parallel
+
+    def add_superpos_task(self, task_id: str) -> None:
+        self._in_flight_superpos_tasks.add(task_id)
+
+    def remove_superpos_task(self, task_id: str) -> None:
+        self._in_flight_superpos_tasks.discard(task_id)
+
+    def has_superpos_task(self, task_id: str) -> bool:
+        return task_id in self._in_flight_superpos_tasks
+
+    # ── /stop support ─────────────────────────────────────────────────
+
+    def _track_chat_task(
+        self, chat_id: int | str, task: asyncio.Task,
+    ) -> None:
+        """Register an in-flight asyncio.Task so ``cancel_chat`` can find it.
+
+        Subclasses should call this from ``_execute`` (or wherever the
+        per-request worker is spawned) right after they create the task,
+        then trust the auto-removal on done.  Calling more than once for
+        the same chat is fine — a chat with parallel work (e.g. branch-
+        scoped tasks) gets a set of tasks tracked.
+        """
+        key = str(chat_id)
+        bucket = self._chat_tasks.setdefault(key, set())
+        bucket.add(task)
+        task.add_done_callback(lambda _t: self._untrack_chat_task(key, _t))
+
+    def _untrack_chat_task(self, chat_key: str, task: asyncio.Task) -> None:
+        bucket = self._chat_tasks.get(chat_key)
+        if not bucket:
+            return
+        bucket.discard(task)
+        if not bucket:
+            self._chat_tasks.pop(chat_key, None)
+
+    def cancel_chat(self, chat_id: int | str) -> int:
+        """Cancel every in-flight task tracked for ``chat_id``.
+
+        Returns the number of tasks signalled (which may be 0 if nothing
+        was running).  Subclasses that need richer behaviour (kill a
+        subprocess, send a Telegram "stopped" message, mark the Superpos
+        task as failed) should override and call ``super().cancel_chat``
+        to keep the asyncio cancellation path uniform.
+        """
+        bucket = self._chat_tasks.get(str(chat_id))
+        if not bucket:
+            return 0
+        cancelled = 0
+        for task in list(bucket):
+            if not task.done():
+                task.cancel()
+                cancelled += 1
+        return cancelled