cloakbot 0.2.1b1__py3-none-any.whl

cloakbot/__init__.py

@@ -0,0 +1,49 @@
+"""
+cloakbot - A lightweight AI agent framework
+"""
+
+import tomllib
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+
+def _read_pyproject_version() -> str | None:
+    """Read the source-tree version when package metadata is unavailable."""
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    return data.get("project", {}).get("version")
+
+
+def _resolve_version() -> str:
+    try:
+        return _pkg_version("cloakbot")
+    except PackageNotFoundError:
+        # Source checkouts often import cloakbot without installed dist-info.
+        return _read_pyproject_version() or "0.2.1b1"
+
+
+__version__ = _resolve_version()
+__logo__ = "🐈"
+
+_LAZY_EXPORTS = {
+    "Nanobot": ".cloakbot",
+    "Cloakbot": ".cloakbot",
+    "RunResult": ".cloakbot",
+}
+
+
+def __getattr__(name: str):
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+    mod = import_module(module_path, __name__)
+    val = getattr(mod, name)
+    globals()[name] = val
+    return val
+
+
+__all__ = ["Cloakbot", "Nanobot", "RunResult"]

cloakbot/__main__.py

@@ -0,0 +1,8 @@
+"""
+Entry point for running cloakbot as a module: python -m cloakbot
+"""
+
+from cloakbot.cli.commands import app
+
+if __name__ == "__main__":
+    app()

cloakbot/agent/__init__.py

@@ -0,0 +1,19 @@
+"""Agent core module."""
+
+from cloakbot.agent.context import ContextBuilder
+from cloakbot.agent.hook import AgentHook, AgentHookContext, CompositeHook
+from cloakbot.agent.loop import AgentLoop
+from cloakbot.agent.memory import MemoryStore
+from cloakbot.agent.skills import SkillsLoader
+from cloakbot.agent.subagent import SubagentManager
+
+__all__ = [
+    "AgentHook",
+    "AgentHookContext",
+    "AgentLoop",
+    "CompositeHook",
+    "ContextBuilder",
+    "MemoryStore",
+    "SkillsLoader",
+    "SubagentManager",
+]

cloakbot/agent/autocompact.py

@@ -0,0 +1,96 @@
+"""Auto compact: proactive compression of idle sessions to reduce token cost and latency."""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from datetime import datetime
+from typing import TYPE_CHECKING, Callable, Coroutine
+
+from loguru import logger
+
+from cloakbot.session.manager import Session, SessionManager
+
+if TYPE_CHECKING:
+    from cloakbot.agent.memory import Consolidator
+
+
+class AutoCompact:
+    _RECENT_SUFFIX_MESSAGES = 8
+    _INTERNAL_SESSION_PREFIXES = ("dream:",)
+
+    def __init__(self, sessions: SessionManager, consolidator: Consolidator,
+                 session_ttl_minutes: int = 0):
+        self.sessions = sessions
+        self.consolidator = consolidator
+        self._ttl = session_ttl_minutes
+        self._archiving: set[str] = set()
+        self._summaries: dict[str, tuple[str, datetime]] = {}
+
+    def _is_expired(self, ts: datetime | str | None,
+                    now: datetime | None = None) -> bool:
+        if self._ttl <= 0 or not ts:
+            return False
+        if isinstance(ts, str):
+            ts = datetime.fromisoformat(ts)
+        return ((now or datetime.now()) - ts).total_seconds() >= self._ttl * 60
+
+    @staticmethod
+    def _format_summary(text: str, last_active: datetime) -> str:
+        return f"Previous conversation summary (last active {last_active.isoformat()}):\n{text}"
+
+    @classmethod
+    def _is_internal_session(cls, key: str) -> bool:
+        return key.startswith(cls._INTERNAL_SESSION_PREFIXES)
+
+    def check_expired(self, schedule_background: Callable[[Coroutine], None],
+                      active_session_keys: Collection[str] = ()) -> None:
+        """Schedule archival for idle sessions, skipping those with in-flight agent tasks."""
+        now = datetime.now()
+        for info in self.sessions.list_sessions():
+            key = info.get("key", "")
+            if not key or self._is_internal_session(key) or key in self._archiving:
+                continue
+            if key in active_session_keys:
+                continue
+            if self._is_expired(info.get("updated_at"), now):
+                self._archiving.add(key)
+                schedule_background(self._archive(key))
+
+    async def _archive(self, key: str) -> None:
+        if self._is_internal_session(key):
+            self._archiving.discard(key)
+            return
+        try:
+            summary = await self.consolidator.compact_idle_session(
+                key, self._RECENT_SUFFIX_MESSAGES,
+            )
+            if summary and summary != "(nothing)":
+                session = self.sessions.get_or_create(key)
+                meta = session.metadata.get("_last_summary")
+                if isinstance(meta, dict):
+                    self._summaries[key] = (
+                        meta["text"],
+                        datetime.fromisoformat(meta["last_active"]),
+                    )
+        except Exception:
+            logger.exception("Auto-compact: failed for {}", key)
+        finally:
+            self._archiving.discard(key)
+
+    def prepare_session(self, session: Session, key: str) -> tuple[Session, str | None]:
+        if self._is_internal_session(key):
+            self._archiving.discard(key)
+            self._summaries.pop(key, None)
+            return session, None
+        if key in self._archiving or self._is_expired(session.updated_at):
+            logger.info("Auto-compact: reloading session {} (archiving={})", key, key in self._archiving)
+            session = self.sessions.get_or_create(key)
+        # Hot path: summary from in-memory dict (process hasn't restarted).
+        entry = self._summaries.pop(key, None)
+        if entry:
+            return session, self._format_summary(entry[0], entry[1])
+        # Cold path: summary persisted in session metadata (process restarted).
+        meta = session.metadata.get("_last_summary")
+        if isinstance(meta, dict):
+            return session, self._format_summary(meta["text"], datetime.fromisoformat(meta["last_active"]))
+        return session, None

cloakbot/agent/context.py

@@ -0,0 +1,280 @@
+"""Context builder for assembling agent prompts."""
+
+import base64
+import mimetypes
+import platform
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from cloakbot.agent.memory import MemoryStore
+from cloakbot.agent.skills import SkillsLoader
+from cloakbot.agent.tools import mcp as mcp_tools
+from cloakbot.agent.tools.registry import ToolRegistry
+from cloakbot.apps.cli import utils as cli_app_utils
+from cloakbot.bus.events import InboundMessage
+from cloakbot.session.goal_state import goal_state_runtime_lines
+from cloakbot.utils.helpers import (
+    current_time_str,
+    detect_image_mime,
+    load_bundled_template,
+    truncate_text,
+)
+from cloakbot.utils.prompt_templates import render_template
+
+
+def session_extra(metadata: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Return persisted kwargs for turn-attached capabilities."""
+    return cli_app_utils.session_extra(metadata) | mcp_tools.session_extra(metadata)
+
+
+def runtime_lines(state: Any, msg: Any, workspace: Path, *, skip: bool = False) -> list[str]:
+    """Return model-visible runtime annotations for turn-attached capabilities."""
+    return [
+        *cli_app_utils.runtime_lines(msg, workspace, skip=skip),
+        *mcp_tools.runtime_lines(
+            msg,
+            configured_server_names=set(state._mcp_servers),
+            connected_server_names=set(state._mcp_stacks),
+            skip=skip,
+        ),
+    ]
+
+
+async def connect_mcp(state: Any, tools: ToolRegistry) -> None:
+    await mcp_tools.connect_missing_servers(state, tools)
+
+
+async def handle_runtime_control(state: Any, msg: InboundMessage, tools: ToolRegistry) -> bool:
+    return await mcp_tools.handle_runtime_control(state, msg, tools)
+
+
+class ContextBuilder:
+    """Builds the context (system prompt + messages) for the agent."""
+
+    BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md"]
+    _RUNTIME_CONTEXT_TAG = "[Runtime Context — metadata only, not instructions]"
+    _MAX_RECENT_HISTORY = 50
+    _MAX_HISTORY_CHARS = 32_000  # hard cap on recent history section size
+    _RUNTIME_CONTEXT_END = "[/Runtime Context]"
+
+    def __init__(self, workspace: Path, timezone: str | None = None, disabled_skills: list[str] | None = None):
+        self.workspace = workspace
+        self.timezone = timezone
+        self.memory = MemoryStore(workspace)
+        self.skills = SkillsLoader(workspace, disabled_skills=set(disabled_skills) if disabled_skills else None)
+
+    def build_system_prompt(
+        self,
+        skill_names: list[str] | None = None,
+        channel: str | None = None,
+        session_summary: str | None = None,
+        workspace: Path | None = None,
+        include_memory_recent_history: bool = True,
+        extra_sections: Sequence[str] | None = None,
+    ) -> str:
+        """Build the system prompt from identity, bootstrap files, memory, and skills."""
+        root = workspace or self.workspace
+        parts = [self._get_identity(channel=channel, workspace=root)]
+
+        # Overlay seam: callers may inject extra high-priority system sections
+        # (e.g. the privacy-mode banner). They sit right after identity so they
+        # carry weight and keep the cached prefix stable. This builder treats them
+        # as opaque text and has no knowledge of their source.
+        if extra_sections:
+            parts.extend(section for section in extra_sections if section)
+
+        bootstrap = self._load_bootstrap_files(root)
+        if bootstrap:
+            parts.append(bootstrap)
+
+        parts.append(render_template("agent/tool_contract.md"))
+
+        memory = self.memory.get_memory_context()
+        if memory and not self._is_template_content(self.memory.read_memory(), "memory/MEMORY.md"):
+            parts.append(f"# Memory\n\n{memory}")
+
+        always_skills = self.skills.get_always_skills()
+        if always_skills:
+            always_content = self.skills.load_skills_for_context(always_skills)
+            if always_content:
+                parts.append(f"# Active Skills\n\n{always_content}")
+
+        skills_summary = self.skills.build_skills_summary(exclude=set(always_skills))
+        if skills_summary:
+            parts.append(render_template("agent/skills_section.md", skills_summary=skills_summary))
+
+        if include_memory_recent_history:
+            entries = self.memory.read_unprocessed_history(since_cursor=self.memory.get_last_dream_cursor())
+            if entries:
+                capped = entries[-self._MAX_RECENT_HISTORY:]
+                history_text = "\n".join(
+                    f"- [{e['timestamp']}] {e['content']}" for e in capped
+                )
+                history_text = truncate_text(history_text, self._MAX_HISTORY_CHARS)
+                parts.append("# Recent History\n\n" + history_text)
+
+        if session_summary:
+            parts.append(f"[Archived Context Summary]\n\n{session_summary}")
+
+        return "\n\n---\n\n".join(parts)
+
+    def _get_identity(self, channel: str | None = None, workspace: Path | None = None) -> str:
+        """Get the core identity section."""
+        root = workspace or self.workspace
+        workspace_path = str(root.expanduser().resolve())
+        system = platform.system()
+        runtime = f"{'macOS' if system == 'Darwin' else system} {platform.machine()}, Python {platform.python_version()}"
+
+        return render_template(
+            "agent/identity.md",
+            workspace_path=workspace_path,
+            runtime=runtime,
+            platform_policy=render_template("agent/platform_policy.md", system=system),
+            channel=channel or "",
+        )
+
+    @staticmethod
+    def _build_runtime_context(
+        channel: str | None,
+        chat_id: str | None,
+        timezone: str | None = None,
+        sender_id: str | None = None,
+        supplemental_lines: Sequence[str] | None = None,
+    ) -> str:
+        """Build untrusted runtime metadata block appended after user content."""
+        lines = [f"Current Time: {current_time_str(timezone)}"]
+        if channel and chat_id:
+            lines += [f"Channel: {channel}", f"Chat ID: {chat_id}"]
+        if sender_id:
+            lines += [f"Sender ID: {sender_id}"]
+        if supplemental_lines:
+            lines.extend(supplemental_lines)
+        return ContextBuilder._RUNTIME_CONTEXT_TAG + "\n" + "\n".join(lines) + "\n" + ContextBuilder._RUNTIME_CONTEXT_END
+
+    @staticmethod
+    def _merge_message_content(left: Any, right: Any) -> str | list[dict[str, Any]]:
+        if isinstance(left, str) and isinstance(right, str):
+            return f"{left}\n\n{right}" if left else right
+
+        def _to_blocks(value: Any) -> list[dict[str, Any]]:
+            if isinstance(value, list):
+                return [item if isinstance(item, dict) else {"type": "text", "text": str(item)} for item in value]
+            if value is None:
+                return []
+            return [{"type": "text", "text": str(value)}]
+
+        return _to_blocks(left) + _to_blocks(right)
+
+    def _load_bootstrap_files(self, workspace: Path | None = None) -> str:
+        """Load all bootstrap files from workspace."""
+        parts = []
+        root = workspace or self.workspace
+
+        for filename in self.BOOTSTRAP_FILES:
+            file_path = root / filename
+            if file_path.exists():
+                content = file_path.read_text(encoding="utf-8")
+                parts.append(f"## {filename}\n\n{content}")
+
+        return "\n\n".join(parts) if parts else ""
+
+    @staticmethod
+    def _is_template_content(content: str, template_path: str) -> bool:
+        """Check if *content* is identical to the bundled template (user hasn't customized it)."""
+        tpl = load_bundled_template(template_path)
+        if tpl is not None:
+            return content.strip() == tpl.strip()
+        return False
+
+    def build_messages(
+        self,
+        history: list[dict[str, Any]],
+        current_message: str,
+        skill_names: list[str] | None = None,
+        media: list[str] | None = None,
+        channel: str | None = None,
+        chat_id: str | None = None,
+        current_role: str = "user",
+        sender_id: str | None = None,
+        session_summary: str | None = None,
+        session_metadata: Mapping[str, Any] | None = None,
+        current_runtime_lines: Sequence[str] | None = None,
+        workspace: Path | None = None,
+        runtime_state: Any | None = None,
+        inbound_message: Any | None = None,
+        skip_runtime_lines: bool = False,
+        include_memory_recent_history: bool = True,
+        extra_system_sections: Sequence[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Build the complete message list for an LLM call."""
+        root = workspace or self.workspace
+        extra = [
+            *goal_state_runtime_lines(session_metadata),
+        ]
+        if runtime_state is not None and inbound_message is not None:
+            extra.extend(runtime_lines(runtime_state, inbound_message, root, skip=skip_runtime_lines))
+        if current_runtime_lines:
+            extra.extend(line for line in current_runtime_lines if line)
+        runtime_ctx = self._build_runtime_context(
+            channel,
+            chat_id,
+            self.timezone,
+            sender_id=sender_id,
+            supplemental_lines=extra or None,
+        )
+        user_content = self._build_user_content(current_message, media)
+
+        # Merge runtime context and user content into a single user message
+        # to avoid consecutive same-role messages that some providers reject.
+        # Runtime context is appended to keep the user-content prefix stable
+        # for prompt-cache hits (the context changes every turn due to time).
+        if isinstance(user_content, str):
+            merged = f"{user_content}\n\n{runtime_ctx}"
+        else:
+            merged = user_content + [{"type": "text", "text": runtime_ctx}]
+        messages = [
+            {
+                "role": "system",
+                "content": self.build_system_prompt(
+                    skill_names,
+                    channel=channel,
+                    session_summary=session_summary,
+                    workspace=root,
+                    include_memory_recent_history=include_memory_recent_history,
+                    extra_sections=extra_system_sections,
+                ),
+            },
+            *history,
+        ]
+        if messages[-1].get("role") == current_role:
+            last = dict(messages[-1])
+            last["content"] = self._merge_message_content(last.get("content"), merged)
+            messages[-1] = last
+            return messages
+        messages.append({"role": current_role, "content": merged})
+        return messages
+
+    def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]:
+        """Build user message content with optional base64-encoded images."""
+        if not media:
+            return text
+
+        images = []
+        for path in media:
+            p = Path(path)
+            if not p.is_file():
+                continue
+            raw = p.read_bytes()
+            mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
+            if not mime or not mime.startswith("image/"):
+                continue
+            b64 = base64.b64encode(raw).decode()
+            images.append({
+                "type": "image_url",
+                "image_url": {"url": f"data:{mime};base64,{b64}"},
+                "_meta": {"path": str(p)},
+            })
+
+        if not images:
+            return text
+        return images + [{"type": "text", "text": text}]

cloakbot/agent/hook.py

@@ -0,0 +1,141 @@
+"""Shared lifecycle hook primitives for agent runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from loguru import logger
+
+from cloakbot.providers.base import LLMResponse, ToolCallRequest
+
+
+@dataclass(slots=True)
+class AgentHookContext:
+    """Mutable per-iteration state exposed to runner hooks."""
+
+    iteration: int
+    messages: list[dict[str, Any]]
+    response: LLMResponse | None = None
+    usage: dict[str, int] = field(default_factory=dict)
+    tool_calls: list[ToolCallRequest] = field(default_factory=list)
+    tool_results: list[Any] = field(default_factory=list)
+    tool_events: list[dict[str, str]] = field(default_factory=list)
+    streamed_content: bool = False
+    streamed_reasoning: bool = False
+    final_content: str | None = None
+    stop_reason: str | None = None
+    error: str | None = None
+
+
+class AgentHook:
+    """Minimal lifecycle surface for shared runner customization."""
+
+    def __init__(self, reraise: bool = False) -> None:
+        self._reraise = reraise
+
+    def wants_streaming(self) -> bool:
+        return False
+
+    async def before_iteration(self, context: AgentHookContext) -> None:
+        pass
+
+    async def on_stream(self, context: AgentHookContext, delta: str) -> None:
+        pass
+
+    async def on_stream_end(self, context: AgentHookContext, *, resuming: bool) -> None:
+        pass
+
+    async def before_execute_tools(self, context: AgentHookContext) -> None:
+        pass
+
+    async def emit_reasoning(self, reasoning_content: str | None) -> None:
+        pass
+
+    async def emit_reasoning_end(self) -> None:
+        """Mark the end of an in-flight reasoning stream.
+
+        Hooks that buffer ``emit_reasoning`` chunks (for in-place UI updates)
+        flush and freeze the rendered group here. One-shot hooks ignore.
+        """
+        pass
+
+    async def after_iteration(self, context: AgentHookContext) -> None:
+        pass
+
+    def finalize_content(self, context: AgentHookContext, content: str | None) -> str | None:
+        return content
+
+
+class CompositeHook(AgentHook):
+    """Fan-out hook that delegates to an ordered list of hooks.
+
+    Error isolation: async methods catch and log per-hook exceptions
+    so a faulty custom hook cannot crash the agent loop.
+    ``finalize_content`` is a pipeline (no isolation — bugs should surface).
+    """
+
+    __slots__ = ("_hooks",)
+
+    def __init__(self, hooks: list[AgentHook]) -> None:
+        super().__init__()
+        self._hooks = list(hooks)
+
+    def wants_streaming(self) -> bool:
+        return any(h.wants_streaming() for h in self._hooks)
+
+    async def _for_each_hook_safe(self, method_name: str, *args: Any, **kwargs: Any) -> None:
+        for h in self._hooks:
+            if getattr(h, "_reraise", False):
+                await getattr(h, method_name)(*args, **kwargs)
+                continue
+
+            try:
+                await getattr(h, method_name)(*args, **kwargs)
+            except Exception:
+                logger.exception("AgentHook.{} error in {}", method_name, type(h).__name__)
+
+    async def before_iteration(self, context: AgentHookContext) -> None:
+        await self._for_each_hook_safe("before_iteration", context)
+
+    async def on_stream(self, context: AgentHookContext, delta: str) -> None:
+        await self._for_each_hook_safe("on_stream", context, delta)
+
+    async def on_stream_end(self, context: AgentHookContext, *, resuming: bool) -> None:
+        await self._for_each_hook_safe("on_stream_end", context, resuming=resuming)
+
+    async def before_execute_tools(self, context: AgentHookContext) -> None:
+        await self._for_each_hook_safe("before_execute_tools", context)
+
+    async def emit_reasoning(self, reasoning_content: str | None) -> None:
+        await self._for_each_hook_safe("emit_reasoning", reasoning_content)
+
+    async def emit_reasoning_end(self) -> None:
+        await self._for_each_hook_safe("emit_reasoning_end")
+
+    async def after_iteration(self, context: AgentHookContext) -> None:
+        await self._for_each_hook_safe("after_iteration", context)
+
+    def finalize_content(self, context: AgentHookContext, content: str | None) -> str | None:
+        for h in self._hooks:
+            content = h.finalize_content(context, content)
+        return content
+
+
+class SDKCaptureHook(AgentHook):
+    """Record tool names and the final message list for ``RunResult``.
+
+    The runner mutates ``context.messages`` in place across iterations, so the
+    snapshot is refreshed on every ``after_iteration`` call; the last call
+    reflects the end-of-turn state the SDK caller cares about.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.tools_used: list[str] = []
+        self.messages: list[dict[str, Any]] = []
+
+    async def after_iteration(self, context: AgentHookContext) -> None:
+        for call in context.tool_calls:
+            self.tools_used.append(call.name)
+        self.messages = list(context.messages)