monkeybot 2.1.1__py3-none-any.whl

monkeybot/__init__.py

@@ -0,0 +1,3 @@
+"""monkeybot — thin owned agent harness."""
+
+__version__ = "2.0.0"

monkeybot/cli/__init__.py

@@ -0,0 +1,3 @@
+"""MonkeyBot CLI."""
+
+from __future__ import annotations

monkeybot/cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entrypoint for ``python -m monkeybot.cli``."""
+
+from __future__ import annotations
+
+from monkeybot.cli.main import main
+
+if __name__ == "__main__":
+    main()

monkeybot/cli/audio_io.py

@@ -0,0 +1,8 @@
+"""Shim — implementation lives in ``monkeybot_cli.realtime.audio_io``."""
+
+from __future__ import annotations
+
+from monkeybot_cli.realtime.audio_io import *  # noqa: F403
+from monkeybot_cli.realtime.audio_io import AudioIOError, AudioPlayer, AudioRecorder
+
+__all__ = ["AudioIOError", "AudioPlayer", "AudioRecorder"]

monkeybot/cli/gateway_manager.py

@@ -0,0 +1,17 @@
+"""Shim — implementation lives in ``monkeybot_cli.realtime.gateway_manager``."""
+
+from __future__ import annotations
+
+from monkeybot_cli.realtime.gateway_manager import (  # noqa: F401
+    _find_workspace_dir,
+    _url_is_local,
+    start_gateway_if_needed,
+    stop_gateway,
+)
+
+__all__ = [
+    "_find_workspace_dir",
+    "_url_is_local",
+    "start_gateway_if_needed",
+    "stop_gateway",
+]

monkeybot/cli/main.py

@@ -0,0 +1,22 @@
+"""Shim — realtime talk helpers live in ``monkeybot_cli.realtime.session``.
+
+The user-facing ``monkeybot`` console script lives in the ``monkeybot-cli`` package
+(``cli/``). This module re-exports so ``python -m monkeybot.cli`` and legacy imports
+keep working when ``monkeybot-cli`` is installed (root ``dev`` group / ``cli/`` sync).
+"""
+
+from __future__ import annotations
+
+from monkeybot_cli.realtime.session import (  # noqa: F401
+    app,
+    main,
+    run_talk_session,
+    talk,
+    version,
+)
+
+__all__ = ["app", "main", "run_talk_session", "talk", "version"]
+
+
+if __name__ == "__main__":
+    main()

monkeybot/cli/push_to_talk.py

@@ -0,0 +1,12 @@
+"""Shim — implementation lives in ``monkeybot_cli.realtime.push_to_talk``."""
+
+from __future__ import annotations
+
+from monkeybot_cli.realtime import push_to_talk as _impl
+from monkeybot_cli.realtime.push_to_talk import PushToTalkError, PushToTalkGate
+
+# Re-export module attrs so tests can patch ``monkeybot.cli.push_to_talk._HAS_PYNPUT``.
+_HAS_PYNPUT = _impl._HAS_PYNPUT
+keyboard = _impl.keyboard
+
+__all__ = ["PushToTalkError", "PushToTalkGate", "_HAS_PYNPUT", "keyboard"]

monkeybot/cli/realtime_client.py

@@ -0,0 +1,13 @@
+"""Shim — encode helpers live in ``monkeybot_cli.realtime``."""
+
+from __future__ import annotations
+
+from monkeybot_cli.exit_commands import is_exit_command
+from monkeybot_cli.realtime.client import RealtimeClientError
+from monkeybot_cli.realtime.wire_encode import encode_client_frame
+
+__all__ = [
+    "RealtimeClientError",
+    "encode_client_frame",
+    "is_exit_command",
+]

monkeybot/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core agent components for monkeybot v2.
+
+Subpackages (import concrete modules from these paths, e.g.
+``monkeybot.core.runtime.loop``):
+
+- ``types`` — protocols, errors, content blocks, tool definitions
+- ``config`` — bot config, secrets, runtime env mapping
+- ``llm`` — streaming ``Provider`` protocol and per-turn usage; vendor backends in ``monkeybot.providers``
+- ``runtime`` — agent loop and typed streaming events
+- ``context`` — per-turn context assembly and curator
+- ``memory`` — filesystem memory, hook, organizer
+- ``persistence`` — SQLite schema, conversation history, run ids, durable runs
+- ``tools`` — tool executor, workspace I/O, sandbox, terminal, inspector
+- ``mcp`` — MCP client and port types
+- ``prompts`` — system prompt and harness helpers
+- ``hooks`` — lifecycle hook manager
+- ``subagents`` — subprocess worker and spawn protocol
+- ``testing`` — in-repo test doubles (mocks)
+"""

monkeybot/core/attachments/__init__.py

@@ -0,0 +1,22 @@
+"""Session-scoped attachment upload, resolve, freeze, and catalog."""
+
+from .catalog import AttachmentRecord, SessionAttachmentCatalog
+from .config import attachments_enabled_from_env
+from .freeze import freeze_attachments_in_history
+from .resolve import AttachmentResolveError, resolve_messages_for_provider
+from .store import AttachmentStore, FilesystemAttachmentStore, sniff_mime
+from .text import parse_attachment_descriptor_text, render_attachment_descriptor_text
+
+__all__ = [
+    "AttachmentRecord",
+    "AttachmentResolveError",
+    "AttachmentStore",
+    "FilesystemAttachmentStore",
+    "SessionAttachmentCatalog",
+    "attachments_enabled_from_env",
+    "freeze_attachments_in_history",
+    "parse_attachment_descriptor_text",
+    "render_attachment_descriptor_text",
+    "resolve_messages_for_provider",
+    "sniff_mime",
+]

monkeybot/core/attachments/catalog.py

@@ -0,0 +1,62 @@
+"""In-memory session attachment catalog (rebuilt from history on load)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from monkeybot.core.llm.provider import Message
+from monkeybot.core.types.content_blocks import Text
+
+from .text import parse_attachment_descriptor_text
+
+
+@dataclass(frozen=True)
+class AttachmentRecord:
+    attachment_id: str
+    filename: str
+    mime_type: str
+    description: str
+    storage_path: str
+    uploaded_at_ms: int | None = None
+    file_missing: bool = False
+
+
+@dataclass
+class SessionAttachmentCatalog:
+    """Derived cache; history frozen Text lines are the durable source of truth."""
+
+    session_id: str
+    records: dict[str, AttachmentRecord] = field(default_factory=dict)
+
+    def list_records(self) -> list[AttachmentRecord]:
+        return list(self.records.values())
+
+    def contains(self, attachment_id: str) -> bool:
+        return attachment_id in self.records
+
+    def get(self, attachment_id: str) -> AttachmentRecord | None:
+        return self.records.get(attachment_id)
+
+    def upsert(self, record: AttachmentRecord) -> None:
+        self.records[record.attachment_id] = record
+
+    def rebuild_from_history(self, messages: Sequence[Message]) -> None:
+        self.records.clear()
+        for msg in messages:
+            for block in msg.content:
+                if not isinstance(block, Text):
+                    continue
+                parsed = parse_attachment_descriptor_text(block.text)
+                if parsed is None:
+                    continue
+                storage_path = (
+                    f".monkeybot/attachments/{self.session_id}/{parsed.attachment_id}"
+                )
+                self.records[parsed.attachment_id] = AttachmentRecord(
+                    attachment_id=parsed.attachment_id,
+                    filename=parsed.filename,
+                    mime_type=parsed.mime_type,
+                    description=parsed.description,
+                    storage_path=storage_path,
+                )

monkeybot/core/attachments/config.py

@@ -0,0 +1,52 @@
+"""Attachment feature flags and limits from environment."""
+
+from __future__ import annotations
+
+import os
+
+ALLOWED_MIME_TYPES: frozenset[str] = frozenset(
+    {
+        "image/jpeg",
+        "image/png",
+        "image/gif",
+        "image/webp",
+        "application/pdf",
+    }
+)
+
+IMAGE_MIME_TYPES: frozenset[str] = frozenset(
+    t for t in ALLOWED_MIME_TYPES if t.startswith("image/")
+)
+
+
+def attachments_enabled_from_env() -> bool:
+    raw = os.getenv("ATTACHMENTS_ENABLED", "true").strip().lower()
+    return raw not in {"0", "false", "no", "off", ""}
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.getenv(name, str(default)).strip()
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return default
+
+
+def max_image_bytes() -> int:
+    return _env_int("ATTACHMENT_MAX_IMAGE_BYTES", 20 * 1024 * 1024)
+
+
+def max_pdf_bytes() -> int:
+    return _env_int("ATTACHMENT_MAX_PDF_BYTES", 50 * 1024 * 1024)
+
+
+def max_attachments_per_session() -> int:
+    return max(1, _env_int("ATTACHMENT_MAX_PER_SESSION", 50))
+
+
+def max_attachments_per_reply() -> int:
+    return max(1, _env_int("ATTACHMENT_MAX_PER_REPLY", 5))
+
+
+def attachment_ttl_hours() -> int:
+    return max(1, _env_int("ATTACHMENT_TTL_HOURS", 48))

monkeybot/core/attachments/freeze.py

@@ -0,0 +1,158 @@
+"""Freeze attachment refs and tool-result media to Text in history."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from monkeybot.core.llm.provider import Message
+from monkeybot.core.persistence.backends import HistoryStore
+from monkeybot.core.runtime.events import AttachmentDescriptorEvent
+from monkeybot.core.types.content_blocks import (
+    AttachmentRef,
+    ContentBlock,
+    File,
+    Image,
+    Text,
+    ToolResponse,
+)
+
+from .catalog import AttachmentRecord, SessionAttachmentCatalog
+from .text import (
+    filename_from_metadata,
+    render_attachment_descriptor_text,
+    render_tool_media_freeze_text,
+)
+
+
+def _freeze_user_row(
+    msg: Message,
+    *,
+    thread_id: str,
+    last_assistant_text: str,
+    catalog: SessionAttachmentCatalog | None,
+    events: list[AttachmentDescriptorEvent],
+) -> Message:
+    user_text = " ".join(
+        b.text.strip() for b in msg.content if isinstance(b, Text) and b.text.strip()
+    )
+    new_content: list[ContentBlock] = []
+    for block in msg.content:
+        if isinstance(block, Text):
+            new_content.append(block)
+            continue
+        if not isinstance(block, AttachmentRef):
+            new_content.append(block)
+            continue
+        filename = filename_from_metadata(block.metadata, fallback=block.attachment_id)
+        description = last_assistant_text.strip() or user_text
+        if not description:
+            description = f"{filename} ({block.mime_type}) attached by user."
+        frozen_text = render_attachment_descriptor_text(
+            attachment_id=block.attachment_id,
+            mime_type=block.mime_type,
+            filename=filename,
+            description=description,
+        )
+        new_content.append(Text(text=frozen_text))
+        events.append(
+            AttachmentDescriptorEvent(
+                attachment_id=block.attachment_id,
+                mime_type=block.mime_type,
+                filename=filename,
+                description=description[:500],
+            )
+        )
+        if catalog is not None:
+            catalog.upsert(
+                AttachmentRecord(
+                    attachment_id=block.attachment_id,
+                    filename=filename,
+                    mime_type=block.mime_type,
+                    description=description[:500],
+                    storage_path=f".monkeybot/attachments/{thread_id}/{block.attachment_id}",
+                )
+            )
+    return Message(role=msg.role, content=new_content)
+
+
+def _freeze_tool_responses(msg: Message) -> Message:
+    new_content: list[ContentBlock] = []
+    changed = False
+    for block in msg.content:
+        if not isinstance(block, ToolResponse):
+            new_content.append(block)
+            continue
+        if not any(isinstance(b, (Image, File)) for b in block.result):
+            new_content.append(block)
+            continue
+        kind = "image" if any(isinstance(b, Image) for b in block.result) else "file"
+        if any(
+            isinstance(b, File) and b.mime_type == "application/pdf" for b in block.result
+        ):
+            kind = "pdf"
+        attachment_id: str | None = None
+        for b in block.result:
+            if isinstance(b, Image):
+                meta = b.metadata or {}
+                att_raw = meta.get("attachment_id")
+                if isinstance(att_raw, str) and att_raw.strip():
+                    attachment_id = att_raw.strip()
+                    break
+        summary = render_tool_media_freeze_text(
+            tool_name=block.tool_name,
+            attachment_id=attachment_id,
+            kind=kind,
+        )
+        changed = True
+        new_content.append(
+            ToolResponse(
+                id=block.id,
+                tool_name=block.tool_name,
+                result=[Text(text=summary)],
+                is_error=block.is_error,
+            )
+        )
+    if not changed:
+        return msg
+    return Message(role=msg.role, content=new_content)
+
+
+async def freeze_attachments_in_history(
+    *,
+    thread_id: str,
+    history: HistoryStore,
+    catalog: SessionAttachmentCatalog | None,
+    last_assistant_text: str,
+) -> list[AttachmentDescriptorEvent]:
+    """Rewrite user attachmentRef rows and tool-result media to Text; return SSE events."""
+    rows = await history.load(thread_id)
+    mutated: list[Message] = []
+    events: list[AttachmentDescriptorEvent] = []
+    changed = False
+
+    for msg in rows:
+        frozen_msg = msg
+        if msg.role == "user" and any(isinstance(b, AttachmentRef) for b in msg.content):
+            frozen_msg = _freeze_user_row(
+                msg,
+                thread_id=thread_id,
+                last_assistant_text=last_assistant_text,
+                catalog=catalog,
+                events=events,
+            )
+            changed = True
+        tool_frozen = _freeze_tool_responses(frozen_msg)
+        if tool_frozen is not frozen_msg:
+            changed = True
+        mutated.append(tool_frozen)
+
+    if changed:
+        await history.reset(thread_id, mutated)
+    return events
+
+
+def ensure_catalog_from_history(
+    catalog: SessionAttachmentCatalog,
+    messages: Sequence[Message],
+) -> None:
+    catalog.rebuild_from_history(messages)

monkeybot/core/attachments/resolve.py

@@ -0,0 +1,70 @@
+"""Resolve attachmentRef blocks to Image/File for provider calls."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Sequence
+
+from monkeybot.core.llm.provider import Message
+from monkeybot.core.types.content_blocks import (
+    AttachmentRef,
+    ContentBlock,
+    File,
+    Image,
+    Text,
+    ToolResponse,
+)
+from monkeybot.core.types.interfaces import MonkeybotError
+
+from .config import IMAGE_MIME_TYPES
+from .store import AttachmentStore
+
+
+class AttachmentResolveError(MonkeybotError):
+    """Failed to load attachment bytes for provider resolution."""
+
+
+def _ref_to_media(
+    store: AttachmentStore,
+    session_id: str,
+    ref: AttachmentRef,
+) -> Image | File:
+    try:
+        data_b64, mime, _filename = store.read_base64(session_id, ref.attachment_id)
+    except FileNotFoundError as exc:
+        raise AttachmentResolveError(str(exc)) from exc
+    mime_use = ref.mime_type or mime
+    meta = dict(ref.metadata) if ref.metadata else None
+    if mime_use in IMAGE_MIME_TYPES:
+        return Image(mime_type=mime_use, data=data_b64, metadata=meta)
+    return File(mime_type=mime_use, data=data_b64, metadata=meta)
+
+
+def _resolve_user_content(blocks: list[ContentBlock], store: AttachmentStore, session_id: str) -> list[ContentBlock]:
+    out: list[ContentBlock] = []
+    for block in blocks:
+        if isinstance(block, AttachmentRef):
+            out.append(_ref_to_media(store, session_id, block))
+        else:
+            out.append(block)
+    return out
+
+
+def resolve_messages_for_provider(
+    messages: Sequence[Message],
+    *,
+    attachment_store: AttachmentStore | None,
+    session_id: str,
+) -> list[Message]:
+    """Return a copy of messages with live attachmentRef rows resolved to Image/File."""
+    if attachment_store is None:
+        return list(messages)
+
+    resolved: list[Message] = []
+    for msg in copy.deepcopy(list(messages)):
+        if msg.role != "user" or not any(isinstance(b, AttachmentRef) for b in msg.content):
+            resolved.append(msg)
+            continue
+        new_content = _resolve_user_content(list(msg.content), attachment_store, session_id)
+        resolved.append(Message(role=msg.role, content=new_content))
+    return resolved

monkeybot/core/attachments/store.py

@@ -0,0 +1,180 @@
+"""Filesystem-backed session attachment store."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from monkeybot.core.path_safety import sanitize_path_component
+from monkeybot.core.attachments.config import (
+    ALLOWED_MIME_TYPES,
+    IMAGE_MIME_TYPES,
+    attachment_ttl_hours,
+    max_attachments_per_session,
+    max_image_bytes,
+    max_pdf_bytes,
+)
+
+
+class AttachmentStoreError(Exception):
+    """Base error for attachment store operations."""
+
+
+class AttachmentTooLargeError(AttachmentStoreError):
+    pass
+
+
+class UnsupportedAttachmentTypeError(AttachmentStoreError):
+    pass
+
+
+class AttachmentSessionLimitError(AttachmentStoreError):
+    pass
+
+
+@dataclass(frozen=True)
+class StoredAttachment:
+    attachment_id: str
+    mime_type: str
+    size_bytes: int
+    filename: str
+    created_at_ms: int
+
+
+def sniff_mime(header: bytes) -> str | None:
+    if header[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+    if header[:3] == b"\xff\xd8\xff":
+        return "image/jpeg"
+    if header[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if len(header) >= 12 and header[:4] == b"RIFF" and header[8:12] == b"WEBP":
+        return "image/webp"
+    if header[:5] == b"%PDF-":
+        return "application/pdf"
+    return None
+
+
+def new_attachment_id() -> str:
+    return f"att_{uuid.uuid4().hex}"
+
+
+class AttachmentStore(Protocol):
+    def exists(self, session_id: str, attachment_id: str) -> bool: ...
+
+    def count_session(self, session_id: str) -> int: ...
+
+    def save(
+        self,
+        session_id: str,
+        *,
+        data: bytes,
+        mime_type: str,
+        filename: str,
+    ) -> StoredAttachment: ...
+
+    def read(self, session_id: str, attachment_id: str) -> tuple[bytes, str, str]: ...
+
+    def read_base64(self, session_id: str, attachment_id: str) -> tuple[str, str, str]: ...
+
+
+class FilesystemAttachmentStore:
+    def __init__(self, workspace_root: Path) -> None:
+        self._root = workspace_root.resolve()
+
+    def _session_dir(self, session_id: str) -> Path:
+        return self._root / ".monkeybot" / "attachments" / sanitize_path_component(session_id)
+
+    def _path_for(self, session_id: str, attachment_id: str) -> Path:
+        return self._session_dir(session_id) / sanitize_path_component(attachment_id)
+
+    def exists(self, session_id: str, attachment_id: str) -> bool:
+        return self._path_for(session_id, attachment_id).is_file()
+
+    def count_session(self, session_id: str) -> int:
+        d = self._session_dir(session_id)
+        if not d.is_dir():
+            return 0
+        return sum(1 for p in d.iterdir() if p.is_file() and not p.name.endswith(".json"))
+
+    def save(
+        self,
+        session_id: str,
+        *,
+        data: bytes,
+        mime_type: str,
+        filename: str,
+    ) -> StoredAttachment:
+        if mime_type not in ALLOWED_MIME_TYPES:
+            raise UnsupportedAttachmentTypeError(f"unsupported mime type: {mime_type}")
+        max_bytes = max_image_bytes() if mime_type in IMAGE_MIME_TYPES else max_pdf_bytes()
+        if len(data) > max_bytes:
+            raise AttachmentTooLargeError(f"attachment exceeds {max_bytes} bytes")
+        sniffed = sniff_mime(data[:512])
+        if sniffed is not None and sniffed != mime_type:
+            raise UnsupportedAttachmentTypeError(
+                f"declared mime {mime_type!r} does not match content ({sniffed})"
+            )
+        if self.count_session(session_id) >= max_attachments_per_session():
+            raise AttachmentSessionLimitError("session attachment limit reached")
+
+        attachment_id = new_attachment_id()
+        path = self._path_for(session_id, attachment_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+        created_at_ms = int(time.time() * 1000)
+        meta_path = path.with_suffix(path.suffix + ".json")
+        meta_path.write_text(
+            json.dumps(
+                {
+                    "attachment_id": attachment_id,
+                    "mime_type": mime_type,
+                    "filename": filename,
+                    "size_bytes": len(data),
+                    "created_at_ms": created_at_ms,
+                }
+            ),
+            encoding="utf-8",
+        )
+        return StoredAttachment(
+            attachment_id=attachment_id,
+            mime_type=mime_type,
+            size_bytes=len(data),
+            filename=filename,
+            created_at_ms=created_at_ms,
+        )
+
+    def read(self, session_id: str, attachment_id: str) -> tuple[bytes, str, str]:
+        path = self._path_for(session_id, attachment_id)
+        if not path.is_file():
+            raise FileNotFoundError(f"attachment not found: {attachment_id}")
+        self._check_ttl(path)
+        meta = self._read_meta(path)
+        mime = str(meta.get("mime_type", "application/octet-stream"))
+        filename = str(meta.get("filename", attachment_id))
+        return path.read_bytes(), mime, filename
+
+    def read_base64(self, session_id: str, attachment_id: str) -> tuple[str, str, str]:
+        data, mime, filename = self.read(session_id, attachment_id)
+        return base64.b64encode(data).decode("ascii"), mime, filename
+
+    def _read_meta(self, path: Path) -> dict[str, object]:
+        meta_path = path.with_suffix(path.suffix + ".json")
+        if meta_path.is_file():
+            raw = json.loads(meta_path.read_text(encoding="utf-8"))
+            if isinstance(raw, dict):
+                return raw
+        return {}
+
+    def _check_ttl(self, path: Path) -> None:
+        meta = self._read_meta(path)
+        created = meta.get("created_at_ms")
+        if isinstance(created, (int, float)):
+            age_ms = int(time.time() * 1000) - int(created)
+            if age_ms > attachment_ttl_hours() * 3600 * 1000:
+                raise FileNotFoundError("attachment expired")