openagent-framework 0.2.6__tar.gz → 0.2.8__tar.gz

{openagent_framework-0.2.6 → openagent_framework-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openagent-framework
-Version: 0.2.6
+Version: 0.2.8
 Summary: Simplified LLM agent framework with MCP, memory, and multi-channel support
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -168,6 +168,29 @@ These are handled automatically by OpenAgent — you just write `openagent.yaml`
 
 ---
 
+## System prompt
+
+OpenAgent injects a **framework-level system prompt** in front of your
+user-defined `system_prompt` on every model call. It codifies guidelines
+that apply to every deployment:
+
+- How to use the memory vault (mcpvault tools, wikilinks, tags).
+- Prefer MCP tools over `shell_exec` and ad-hoc scripts.
+- Act autonomously under `permission_mode: bypass`; only stop for
+  ambiguous or irreversible actions.
+- Be concise; lead with the answer, not the reasoning.
+
+Your `system_prompt` in `openagent.yaml` should therefore stay **short
+and project-specific** — just identity and a pointer to the memory
+vault. Everything else (package names, host names, credentials,
+procedures) belongs as `.md` notes inside the vault, where the agent
+will find them via `search_notes`.
+
+The framework prompt source lives at `openagent/prompts.py:FRAMEWORK_SYSTEM_PROMPT`
+if you want to read or tweak the wording.
+
+---
+
 ## Memory
 
 OpenAgent's long-term memory is a plain **Obsidian-compatible markdown vault**. The agent reads and writes `.md` files directly via the [`mcpvault`](https://www.npmjs.com/package/@bitbonsai/mcpvault) MCP — no custom index, no full-text engine, no proprietary format. The files on disk *are* the database.

{openagent_framework-0.2.6 → openagent_framework-0.2.8}/docs/README.md

@@ -141,6 +141,29 @@ These are handled automatically by OpenAgent — you just write `openagent.yaml`
 
 ---
 
+## System prompt
+
+OpenAgent injects a **framework-level system prompt** in front of your
+user-defined `system_prompt` on every model call. It codifies guidelines
+that apply to every deployment:
+
+- How to use the memory vault (mcpvault tools, wikilinks, tags).
+- Prefer MCP tools over `shell_exec` and ad-hoc scripts.
+- Act autonomously under `permission_mode: bypass`; only stop for
+  ambiguous or irreversible actions.
+- Be concise; lead with the answer, not the reasoning.
+
+Your `system_prompt` in `openagent.yaml` should therefore stay **short
+and project-specific** — just identity and a pointer to the memory
+vault. Everything else (package names, host names, credentials,
+procedures) belongs as `.md` notes inside the vault, where the agent
+will find them via `search_notes`.
+
+The framework prompt source lives at `openagent/prompts.py:FRAMEWORK_SYSTEM_PROMPT`
+if you want to read or tweak the wording.
+
+---
+
 ## Memory
 
 OpenAgent's long-term memory is a plain **Obsidian-compatible markdown vault**. The agent reads and writes `.md` files directly via the [`mcpvault`](https://www.npmjs.com/package/@bitbonsai/mcpvault) MCP — no custom index, no full-text engine, no proprietary format. The files on disk *are* the database.

{openagent_framework-0.2.6 → openagent_framework-0.2.8}/openagent/__init__.py

@@ -1,5 +1,5 @@
 from openagent.agent import Agent
 from openagent.config import load_config
 
-__version__ = "0.2.6"
+__version__ = "0.2.7"
 __all__ = ["Agent", "load_config"]

{openagent_framework-0.2.6 → openagent_framework-0.2.8}/openagent/agent.py

@@ -8,6 +8,7 @@ from typing import Any, AsyncIterator, Callable, Awaitable
 from openagent.models.base import BaseModel, ModelResponse
 from openagent.memory.db import MemoryDB
 from openagent.mcp.client import MCPRegistry, MCPTools
+from openagent.prompts import FRAMEWORK_SYSTEM_PROMPT
 
 logger = logging.getLogger(__name__)
 
@@ -192,7 +193,9 @@ class Agent:
         """Inner run logic, wrapped by run() for crash protection."""
         await _status("Loading context...")
 
-        system = self.system_prompt
+        # Combine OpenAgent's framework-level guidelines with the user's
+        # project-specific system prompt from openagent.yaml.
+        system = self._combined_system_prompt()
 
         # Build messages
         if attachments:
@@ -244,6 +247,17 @@ class Agent:
 
         return response.content if response else "I wasn't able to complete the request."
 
+    def _combined_system_prompt(self) -> str:
+        """Prepend the framework-level prompt to the user's system prompt."""
+        user = (self.system_prompt or "").strip()
+        if not user:
+            return FRAMEWORK_SYSTEM_PROMPT
+        return (
+            FRAMEWORK_SYSTEM_PROMPT
+            + "\n\n── User-specific identity and project context ──\n\n"
+            + user
+        )
+
     async def stream_run(
         self,
         message: str,
@@ -256,7 +270,7 @@ class Agent:
 
         await self.initialize()
 
-        system = self.system_prompt
+        system = self._combined_system_prompt()
         messages: list[dict[str, Any]] = [{"role": "user", "content": message}]
 
         async for chunk in self.model.stream(messages, system=system):

openagent_framework-0.2.8/openagent/channels/__init__.py

@@ -0,0 +1,22 @@
+from openagent.channels.base import (
+    Attachment,
+    BLOCKED_EXTENSIONS,
+    BaseChannel,
+    is_blocked_attachment,
+    parse_response_markers,
+    split_preserving_code_blocks,
+)
+from openagent.channels.commands import CommandDispatcher, CommandResult
+from openagent.channels.queue import UserQueueManager
+
+__all__ = [
+    "Attachment",
+    "BLOCKED_EXTENSIONS",
+    "BaseChannel",
+    "CommandDispatcher",
+    "CommandResult",
+    "UserQueueManager",
+    "is_blocked_attachment",
+    "parse_response_markers",
+    "split_preserving_code_blocks",
+]

{openagent_framework-0.2.6 → openagent_framework-0.2.8}/openagent/channels/base.py

@@ -74,6 +74,86 @@ def format_attachments_for_prompt(attachments: list[Attachment], caption: str =
     return prefix
 
 
+# File extensions we refuse to download from any channel for basic safety.
+# Shell scripts are NOT on this list — an agent is expected to deal with them
+# legitimately. This is about Windows executables and obviously malicious
+# droppers, not about blocking all code.
+BLOCKED_EXTENSIONS: frozenset[str] = frozenset({
+    ".exe", ".bat", ".cmd", ".com", ".msi", ".scr", ".pif",
+    ".vbs", ".vbe", ".jse", ".ws", ".wsf", ".wsh", ".ps1", ".hta",
+    ".cpl", ".lnk", ".reg", ".jar",
+})
+
+
+def is_blocked_attachment(filename: str | None) -> bool:
+    """Return True if the filename has a blocked extension (case-insensitive)."""
+    if not filename:
+        return False
+    return Path(filename).suffix.lower() in BLOCKED_EXTENSIONS
+
+
+def split_preserving_code_blocks(text: str, max_len: int) -> list[str]:
+    """Split *text* into chunks of ≤ ``max_len`` characters, preserving
+    fenced ``` code blocks so no chunk ends with a dangling fence.
+
+    Strategy:
+
+    1. Walk the text in windows of at most ``max_len`` chars, cutting on a
+       newline when possible.
+    2. For each chunk, count the unescaped ``` fences. If odd, close with a
+       trailing ``` and prepend ``` to the next chunk so the code style
+       carries over to the reader.
+
+    This loses the original language tag after a mid-block split — Discord
+    and Telegram render ``` (no lang) as a plain monospace block, which is
+    still the right thing for long output.
+    """
+    if max_len <= 0:
+        return [text] if text else []
+    if len(text) <= max_len:
+        return [text] if text.strip() else []
+
+    chunks: list[str] = []
+    carry_prefix = ""
+    i = 0
+    n = len(text)
+
+    while i < n:
+        budget = max_len - len(carry_prefix)
+        if budget <= 16:
+            # carry_prefix too large vs max_len; fall back to hard cut
+            budget = max(max_len // 2, 16)
+        end = min(i + budget, n)
+        if end < n:
+            # prefer newline cut, then space, else hard cut
+            nl = text.rfind("\n", i, end)
+            if nl > i + budget // 4:
+                end = nl
+            else:
+                sp = text.rfind(" ", i, end)
+                if sp > i + budget // 4:
+                    end = sp
+
+        body = text[i:end]
+        chunk = carry_prefix + body
+
+        fence_total = chunk.count("```")
+        if fence_total % 2 == 1:
+            chunk = chunk + "\n```"
+            carry_prefix = "```\n"
+        else:
+            carry_prefix = ""
+
+        if chunk.strip():
+            chunks.append(chunk)
+
+        i = end
+        while i < n and text[i] in ("\n", " "):
+            i += 1
+
+    return chunks
+
+
 class BaseChannel(ABC):
     """Abstract base for messaging channels (Telegram, Discord, WhatsApp, etc.).
 

openagent_framework-0.2.8/openagent/channels/commands.py

@@ -0,0 +1,172 @@
+"""Cross-channel slash command dispatcher.
+
+All channels (Telegram, Discord, WhatsApp) share a single command
+vocabulary via ``CommandDispatcher``. Commands are parsed with a leading
+``/`` (e.g. ``/new``, ``/stop``, ``/status``, ``/queue clear``) and resolve
+to a :class:`CommandResult` the channel renders in its native way.
+
+The registered commands are:
+
+- ``/new``    — reset the user's session (fresh context)
+- ``/reset``  — alias of /new
+- ``/stop``   — cancel the currently running task for the user
+- ``/status`` — busy/idle + queue depth + session id tail
+- ``/queue``  — show queue state; ``/queue clear`` empties it
+- ``/help``   — list of commands
+- ``/usage``  — Claude Code usage via ``ccusage`` (claude-cli backend only)
+
+Unknown commands return ``None`` so the channel can either fall through to
+normal message handling or reject them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openagent.agent import Agent
+    from openagent.channels.queue import UserQueueManager
+
+logger = logging.getLogger(__name__)
+
+
+HELP_TEXT = (
+    "Comandi disponibili:\n"
+    "• /new — nuova sessione (contesto fresco)\n"
+    "• /stop — ferma l'operazione in corso\n"
+    "• /status — stato (busy/idle + coda)\n"
+    "• /queue — messaggi in coda\n"
+    "• /queue clear — svuota la coda\n"
+    "• /usage — uso Claude Code (solo backend claude-cli)\n"
+    "• /help — questo messaggio"
+)
+
+
+@dataclass
+class CommandResult:
+    """Result of a command. Rendered verbatim by the channel."""
+    text: str
+    is_error: bool = False
+
+
+class CommandDispatcher:
+    """Parse and dispatch slash commands for a single channel instance."""
+
+    def __init__(self, agent: Agent, queue: UserQueueManager):
+        self.agent = agent
+        self.queue = queue
+
+    @staticmethod
+    def is_command(text: str | None) -> bool:
+        return bool(text) and text.lstrip().startswith("/")
+
+    @staticmethod
+    def parse(text: str) -> tuple[str, str]:
+        """Return (command, argument) stripped of the leading slash."""
+        body = text.lstrip()[1:]
+        parts = body.split(maxsplit=1)
+        cmd = parts[0].lower() if parts else ""
+        # Telegram-style @botname suffix: /new@mybot → /new
+        if "@" in cmd:
+            cmd = cmd.split("@", 1)[0]
+        arg = parts[1] if len(parts) > 1 else ""
+        return cmd, arg
+
+    async def dispatch(self, text: str, user_id: str) -> CommandResult | None:
+        """Run a command. Returns None if the text isn't a known command."""
+        if not self.is_command(text):
+            return None
+        cmd, arg = self.parse(text)
+        method = getattr(self, f"cmd_{cmd.replace('-', '_')}", None)
+        if method is None:
+            return None
+        try:
+            return await method(arg, user_id)
+        except Exception as e:  # noqa: BLE001
+            logger.exception("Command /%s failed", cmd)
+            return CommandResult(f"Errore eseguendo /{cmd}: {e}", is_error=True)
+
+    # ── commands ───────────────────────────────────────────────────────
+
+    async def cmd_new(self, arg: str, user_id: str) -> CommandResult:
+        self.queue.reset_session(user_id)
+        return CommandResult("🆕 Nuova sessione avviata. Contesto precedente archiviato.")
+
+    async def cmd_reset(self, arg: str, user_id: str) -> CommandResult:
+        return await self.cmd_new(arg, user_id)
+
+    async def cmd_stop(self, arg: str, user_id: str) -> CommandResult:
+        stopped = self.queue.stop_current(user_id)
+        if stopped:
+            return CommandResult("⏹ Operazione in corso cancellata.")
+        return CommandResult("Nessuna operazione in corso.")
+
+    async def cmd_status(self, arg: str, user_id: str) -> CommandResult:
+        busy = self.queue.is_busy(user_id)
+        depth = self.queue.queue_depth(user_id)
+        sid = self.queue.get_session_id(user_id)
+        state = "🟢 busy" if busy else "⚪ idle"
+        lines = [
+            "Stato:",
+            f"• Agent: {self.agent.name}",
+            f"• Stato: {state}",
+            f"• In coda: {depth}",
+            f"• Sessione: …{sid[-8:]}",
+        ]
+        return CommandResult("\n".join(lines))
+
+    async def cmd_queue(self, arg: str, user_id: str) -> CommandResult:
+        if arg.strip().lower() in {"clear", "clean", "reset"}:
+            n = self.queue.clear_queue(user_id)
+            return CommandResult(f"🧹 Coda svuotata ({n} messaggi rimossi).")
+        depth = self.queue.queue_depth(user_id)
+        busy = self.queue.is_busy(user_id)
+        if depth == 0 and not busy:
+            return CommandResult("Nessun messaggio in coda.")
+        tail = " (operazione in corso)" if busy else ""
+        return CommandResult(f"📋 In coda: {depth} messaggi{tail}")
+
+    async def cmd_help(self, arg: str, user_id: str) -> CommandResult:
+        return CommandResult(HELP_TEXT)
+
+    async def cmd_usage(self, arg: str, user_id: str) -> CommandResult:
+        from openagent.models.claude_cli import ClaudeCLI
+        if not isinstance(self.agent.model, ClaudeCLI):
+            return CommandResult(
+                "ℹ️ /usage funziona solo con il backend claude-cli.",
+                is_error=True,
+            )
+        npx = shutil.which("npx")
+        if not npx:
+            return CommandResult(
+                "❌ npx non trovato sul PATH (serve Node.js per ccusage).",
+                is_error=True,
+            )
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                npx, "-y", "ccusage@latest",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=45)
+            except asyncio.TimeoutError:
+                proc.kill()
+                return CommandResult("❌ ccusage timeout (45s).", is_error=True)
+        except Exception as e:  # noqa: BLE001
+            return CommandResult(f"❌ Impossibile lanciare ccusage: {e}", is_error=True)
+
+        output = stdout.decode(errors="replace").strip()
+        if not output:
+            output = stderr.decode(errors="replace").strip()
+        if not output:
+            return CommandResult("❌ ccusage non ha restituito output.", is_error=True)
+        # Keep it under 3900 chars to stay under Discord/Telegram limits when
+        # wrapped in a code fence.
+        if len(output) > 3800:
+            output = output[:3800] + "\n… (troncato)"
+        return CommandResult(f"```\n{output}\n```")