monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/attachments/text.py

@@ -0,0 +1,72 @@
+"""Frozen attachment descriptor text render/parse."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ParsedAttachmentDescriptor:
+    attachment_id: str
+    filename: str
+    mime_type: str
+    description: str
+
+
+_ATTACHMENT_LINE_RE = re.compile(
+    r'^\[attachment\s+(?P<id>\S+)\s+(?P<filename>.+?)\s+\((?P<mime>[^)]+)\):\s+'
+    r'(?P<desc>.+?)\.\s+Call read_attachment\("(?P=id)"\)\s+to view pixels again\.\]$'
+)
+
+
+def render_attachment_descriptor_text(
+    *,
+    attachment_id: str,
+    filename: str,
+    mime_type: str,
+    description: str,
+) -> str:
+    desc = description.strip() or f"{filename} ({mime_type}) attached by user."
+    if len(desc) > 500:
+        desc = desc[:497].rstrip() + "..."
+    return (
+        f'[attachment {attachment_id} {filename} ({mime_type}): {desc}. '
+        f'Call read_attachment("{attachment_id}") to view pixels again.]'
+    )
+
+
+def parse_attachment_descriptor_text(text: str) -> ParsedAttachmentDescriptor | None:
+    m = _ATTACHMENT_LINE_RE.match(text.strip())
+    if m is None:
+        return None
+    return ParsedAttachmentDescriptor(
+        attachment_id=m.group("id"),
+        filename=m.group("filename"),
+        mime_type=m.group("mime"),
+        description=m.group("desc"),
+    )
+
+
+def render_tool_media_freeze_text(
+    *,
+    tool_name: str,
+    attachment_id: str | None,
+    kind: str,
+) -> str:
+    if attachment_id:
+        return (
+            f"[{tool_name} {attachment_id} result: {kind} shown earlier; "
+            f'call read_attachment("{attachment_id}") to reload.]'
+        )
+    return f"[{tool_name} result: {kind} shown earlier; call tool again to reload.]"
+
+
+def filename_from_metadata(metadata: dict[str, object] | None, *, fallback: str) -> str:
+    if not metadata:
+        return fallback
+    for key in ("filename", "name"):
+        val = metadata.get(key)
+        if isinstance(val, str) and val.strip():
+            return val.strip()
+    return fallback

monkeybot/core/attachments/tools.py

@@ -0,0 +1,54 @@
+"""Attachment-related tool definitions."""
+
+from __future__ import annotations
+
+from monkeybot.core.types.types_tools import ToolDef
+
+READ_ATTACHMENT_SCHEMA: dict[str, object] = {
+    "type": "object",
+    "properties": {
+        "attachment_id": {
+            "type": "string",
+            "description": "Session attachment id from ## Session attachments.",
+        },
+    },
+    "required": ["attachment_id"],
+}
+
+RENDER_IMAGE_SCHEMA: dict[str, object] = {
+    "type": "object",
+    "properties": {
+        "path": {
+            "type": "string",
+            "description": "Workspace-relative path to a PNG/JPEG/GIF/WebP image file.",
+        },
+        "caption": {
+            "type": "string",
+            "description": "Optional short caption shown with the image in chat.",
+        },
+    },
+    "required": ["path"],
+}
+
+
+def read_attachment_tool_def() -> ToolDef:
+    return ToolDef(
+        "read_attachment",
+        (
+            "Load a session attachment by id for visual or PDF analysis. "
+            "Ids are listed under ## Session attachments when present."
+        ),
+        READ_ATTACHMENT_SCHEMA,
+        parallel_safe=True,
+    )
+
+
+def render_image_tool_def() -> ToolDef:
+    return ToolDef(
+        "render_image",
+        (
+            "Display a workspace image inline in the chat UI. "
+            "Use after skill scripts write PNG/JPEG/GIF/WebP under ./generated-media/ or similar."
+        ),
+        RENDER_IMAGE_SCHEMA,
+    )

monkeybot/core/bootstrap.py

@@ -0,0 +1,242 @@
+"""Optional cold-start wiring for harness-as-library (Pattern B / C).
+
+Callers who prefer explicit construction can ignore this module and wire
+:class:`~monkeybot.core.persistence.backends.StorageBackend`,
+:class:`~monkeybot.core.memory.subsystem.MemorySubsystem`, :class:`~monkeybot.core.mcp.mcp_client.MCPClient`,
+and a :class:`~monkeybot.core.llm.provider.Provider` themselves.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from monkeybot.core.config.settings import auto_schema_enabled_from_config, get_provider_config
+from monkeybot.core.context import build_context
+from monkeybot.core.hooks import HookManager
+from monkeybot.core.llm.provider import Provider
+from monkeybot.core.llm.usage import usage_from_totals
+from monkeybot.core.mcp.mcp_client import MCPClient
+from monkeybot.core.memory.subsystem import MemorySubsystem
+from monkeybot.core.persistence.backends import StorageBackend, create_storage_backend
+from monkeybot.core.runtime.events import AssistantDelta, Error, TurnComplete
+from monkeybot.core.runtime.loop import run as run_loop
+from monkeybot.core.tools.core_tool_executor import CoreToolExecutor
+from monkeybot.core.tools.inspector import load_command_tier_policy
+from monkeybot.core.workspace import create_workspace_storage
+
+logger = logging.getLogger(__name__)
+
+
+class PatternBcTurnError(RuntimeError):
+    """Raised when :func:`run_pattern_bc_turn` receives an :class:`~monkeybot.core.runtime.events.Error` event."""
+
+    def __init__(self, message: str, *, request_id: str = "") -> None:
+        super().__init__(message)
+        self.request_id = request_id
+
+
+@dataclass
+class HarnessDeps:
+    """Process-scoped dependencies for ``build_context`` + ``run_loop``."""
+
+    storage: StorageBackend
+    memory: MemorySubsystem | None
+    mcp: MCPClient
+    provider: Provider
+    model: str
+
+    async def close(self) -> None:
+        """Close persisted storage and tear down MCP sessions.
+
+        :class:`~monkeybot.core.workspace.protocol.WorkspaceStorage` (behind ``memory``)
+        does not define ``aclose``/``close`` today; cloud SDK clients are process-scoped.
+        Call explicit workspace teardown here if the protocol gains lifecycle hooks.
+        """
+        await self.storage.close()
+        await self.mcp.disconnect_all()
+
+
+def _resolve_run_command_allowlists() -> tuple[list[str] | None, list[str] | None]:
+    """Load allowlists from ``COMMAND_ALLOWLIST_CONFIG`` when present; else executor defaults."""
+    path_str = os.environ.get("COMMAND_ALLOWLIST_CONFIG", "").strip()
+    if not path_str:
+        return None, None
+    path = Path(path_str)
+    if not path.is_file():
+        logger.info("command allowlist missing (%s); using CoreToolExecutor defaults", path)
+        return None, None
+    try:
+        policy = load_command_tier_policy(path)
+        return list(policy.allowed_commands), list(policy.allowed_path_prefixes)
+    except Exception as exc:
+        logger.warning("command allowlist load failed (%s): %s", path, exc)
+        return None, None
+
+
+def _env_context_window_tokens() -> int:
+    cap_raw = os.environ.get("MODEL_CONTEXT_WINDOW", "200000").strip()
+    try:
+        return max(1, int(cap_raw))
+    except ValueError:
+        return 200_000
+
+
+async def create_harness_deps(
+    db_url: str,
+    memory_storage_uri: str | None = None,
+    *,
+    mcp_config_path: Path | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    open_mcp: bool = True,
+    provider_override: Provider | None = None,
+    _provider_override: Provider | None = None,
+) -> HarnessDeps:
+    """Open storage, optional memory, MCP, and resolve the LLM provider.
+
+    Args:
+        db_url: Passed to :func:`~monkeybot.core.persistence.backends.create_storage_backend`.
+        memory_storage_uri: When set, passed to :func:`~monkeybot.core.workspace.create_workspace_storage`
+            and wrapped in :class:`~monkeybot.core.memory.subsystem.MemorySubsystem`.
+        mcp_config_path: When ``open_mcp`` is True and this path is a file,
+            :meth:`~monkeybot.core.mcp.mcp_client.MCPClient.load_from_config` is called.
+        provider: ``MODEL_PROVIDER`` override for :func:`~monkeybot.core.config.settings.get_provider_config`.
+        model: Model id override for :func:`~monkeybot.core.config.settings.get_provider_config`.
+        open_mcp: When False, MCP is not loaded from disk (typical for Lambda).
+        provider_override: Inject a custom :class:`~monkeybot.core.llm.provider.Provider` (skips config lookup).
+        _provider_override: Deprecated alias for ``provider_override`` (tests).
+    """
+    override = provider_override if provider_override is not None else _provider_override
+    backend = create_storage_backend(db_url)
+    await backend.open(run_schema=auto_schema_enabled_from_config())
+    try:
+        if override is not None:
+            prov = override
+            model_str = str(model or "test-model")
+        else:
+            pc = get_provider_config(provider=provider, model_name=model)
+            prov = pc.provider
+            model_str = pc.model
+
+        memory: MemorySubsystem | None = None
+        uri = (memory_storage_uri or "").strip()
+        if uri:
+            ws = create_workspace_storage(uri)
+            memory = MemorySubsystem(
+                storage=ws,
+                provider=prov,
+                model=model_str,
+                memory_uri=uri,
+            )
+
+        mcp = MCPClient()
+        if open_mcp and mcp_config_path is not None:
+            strict = os.environ.get("MCP_STRICT_LOAD", "").strip().lower() in ("1", "true", "yes")
+            await mcp.load_from_config(mcp_config_path, raise_on_error=strict)
+
+        return HarnessDeps(
+            storage=backend,
+            memory=memory,
+            mcp=mcp,
+            provider=prov,
+            model=model_str,
+        )
+    except BaseException:
+        await backend.close()
+        raise
+
+
+async def run_pattern_bc_turn(
+    deps: HarnessDeps,
+    message: str,
+    *,
+    session_id: str,
+    request_id: str,
+    agent_md_path: Path,
+    skills_path: Path,
+    workspace_root: Path,
+    hook_manager: HookManager | None = None,
+) -> str:
+    """Run one user message through :func:`~monkeybot.core.context.build_context` + :func:`~monkeybot.core.runtime.loop.run`.
+
+    When ``hook_manager`` is ``None`` (typical for Lambda / short-lived handlers), the loop
+    does not fire :class:`~monkeybot.core.hooks.HookManager` hooks, so :class:`~monkeybot.core.memory.hook.MemoryHook`
+    callbacks (automatic ``POST_TOOL`` / ``POST_TURN`` capture, organizer scheduling) never run.
+    ``deps.memory`` still powers the memory index, ``search_memory``, etc. To enable hook-driven
+    memory in FaaS, construct a ``HookManager``, ``memory.register_hooks(mgr)``, pass ``mgr``,
+    and use positive hook timeouts where needed so work finishes before the handler returns.
+
+    Returns:
+        Concatenated assistant text from :class:`~monkeybot.core.runtime.events.AssistantDelta` events.
+
+    Raises:
+        PatternBcTurnError: When the loop emits an :class:`~monkeybot.core.runtime.events.Error` event.
+    """
+    ctx = await build_context(
+        session_id,
+        request_id,
+        agent_md_path=agent_md_path,
+        memory=deps.memory,
+        skills_path=skills_path,
+        mcp_client=deps.mcp,
+        model=deps.model,
+        include_task_tool=False,
+        sse_bus=None,
+        workspace_root=workspace_root,
+        context_window_tokens=_env_context_window_tokens(),
+    )
+
+    run_cmds, run_paths = _resolve_run_command_allowlists()
+    executor = CoreToolExecutor(
+        workspace_root=workspace_root,
+        memory=deps.memory,
+        skills_path=skills_path,
+        mcp=deps.mcp,
+        run_command_allowed_commands=run_cmds,
+        run_command_allowed_path_prefixes=run_paths,
+    )
+
+    parts: list[str] = []
+    try:
+        async for evt in run_loop(
+            message,
+            ctx,
+            provider=deps.provider,
+            history=deps.storage.history(),
+            inspectors=[],
+            tool_executor=executor,
+            hook_manager=hook_manager,
+        ):
+            if isinstance(evt, Error):
+                logger.error(
+                    "run_pattern_bc_turn failed request_id=%s: %s",
+                    evt.request_id or request_id,
+                    evt.error,
+                )
+                raise PatternBcTurnError(evt.error, request_id=evt.request_id or request_id)
+            if isinstance(evt, AssistantDelta) and evt.delta:
+                parts.append(evt.delta)
+            if isinstance(evt, TurnComplete):
+                await deps.storage.usage().record(
+                    session_id,
+                    deps.model,
+                    usage_from_totals(evt.usage),
+                    run_id=request_id,
+                )
+    finally:
+        await executor.aclose()
+        if deps.memory is not None:
+            await deps.memory.flush()
+
+    return "".join(parts)
+
+
+__all__ = [
+    "HarnessDeps",
+    "PatternBcTurnError",
+    "create_harness_deps",
+    "run_pattern_bc_turn",
+]

monkeybot/core/config/__init__.py

@@ -0,0 +1,71 @@
+"""Configuration utilities for the monkeybot harness."""
+
+from __future__ import annotations
+
+from monkeybot.core.config.realtime_config import (
+    RealtimeAudioConfig,
+    RealtimeConfig,
+    RealtimeMetricsConfig,
+    RealtimeModelConfig,
+    RealtimeSessionConfig,
+    RealtimeWebSocketConfig,
+    get_realtime_config,
+)
+from monkeybot.core.config.runtime_env import (
+    ENV_MAP,
+    apply_monkeybot_runtime_env,
+    reset_runtime_env_state_for_tests,
+)
+from monkeybot.core.config.settings import (
+    ConfigError,
+    CustomMemoryFolder,
+    ProviderConfig,
+    SubagentConfig,
+    auto_schema_enabled_from_config,
+    get_provider_config,
+    get_subagent_configs,
+    get_subagent_registry,
+    normalize_model_provider,
+    subagent_vertex_google_search_from_config,
+    vertex_google_search_enabled_from_config,
+)
+from monkeybot.core.config.validation import (
+    SUPPORTED_MODEL_PROVIDERS,
+    SUPPORTED_YAML_MODEL_PROVIDERS,
+    validate_monkeybot_yaml_doc,
+    validate_provider_env,
+)
+from monkeybot.core.config.yaml_loader import (
+    load_monkeybot_yaml_dict,
+    resolve_monkeybot_config_path,
+)
+
+__all__ = [
+    "ENV_MAP",
+    "ConfigError",
+    "CustomMemoryFolder",
+    "ProviderConfig",
+    "SubagentConfig",
+    "SUPPORTED_MODEL_PROVIDERS",
+    "SUPPORTED_YAML_MODEL_PROVIDERS",
+    "apply_monkeybot_runtime_env",
+    "auto_schema_enabled_from_config",
+    "get_provider_config",
+    "get_subagent_configs",
+    "get_subagent_registry",
+    "load_monkeybot_yaml_dict",
+    "normalize_model_provider",
+    "reset_runtime_env_state_for_tests",
+    "RealtimeAudioConfig",
+    "RealtimeConfig",
+    "RealtimeMetricsConfig",
+    "RealtimeModelConfig",
+    "RealtimeSessionConfig",
+    "RealtimeWebSocketConfig",
+    "get_realtime_config",
+    "resolve_monkeybot_config_path",
+    "validate_monkeybot_yaml_doc",
+    "validate_provider_env",
+    "vertex_google_search_enabled_from_config",
+    "subagent_vertex_google_search_from_config",
+]

monkeybot/core/config/realtime_config.py

@@ -0,0 +1,150 @@
+"""Parsed ``realtime`` section of monkeybot.yaml with defaults."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from monkeybot.core.config.yaml_loader import load_monkeybot_yaml_dict
+
+
+@dataclass(frozen=True)
+class RealtimeAudioConfig:
+    input_format: str = "pcm_s16le_24khz_mono"
+    output_format: str = "pcm_s16le_24khz_mono"
+    chunk_ms: int = 200
+    max_utterance_sec: int = 60
+
+
+@dataclass(frozen=True)
+class RealtimeSessionConfig:
+    max_duration_sec: int = 1800
+    idle_timeout_sec: int = 120
+    max_response_turn_sec: int = 300
+    max_concurrent_sessions: int = 100
+
+
+@dataclass(frozen=True)
+class RealtimeWebSocketConfig:
+    enabled: bool = True
+    port: int | None = None
+
+
+@dataclass(frozen=True)
+class RealtimeMetricsConfig:
+    emit_summary_on_close: bool = True
+
+
+@dataclass(frozen=True)
+class RealtimeModelConfig:
+    """Override the model/provider used for the realtime session.
+
+    Defaults to the main ``model`` section, but some live preview models (e.g.
+    gemini-3.1-flash-live-preview) only support the live API and must be kept separate
+    from turn-based providers like context curation and memory organizer.
+    """
+
+    name: str | None = None
+    provider: str | None = None
+
+
+@dataclass(frozen=True)
+class RealtimeConfig:
+    enabled: bool = False
+    websocket: RealtimeWebSocketConfig = field(default_factory=RealtimeWebSocketConfig)
+    audio: RealtimeAudioConfig = field(default_factory=RealtimeAudioConfig)
+    session: RealtimeSessionConfig = field(default_factory=RealtimeSessionConfig)
+    metrics: RealtimeMetricsConfig = field(default_factory=RealtimeMetricsConfig)
+    model: RealtimeModelConfig = field(default_factory=RealtimeModelConfig)
+
+
+def _nested_get(mapping: Any, *path: str, default: Any = None) -> Any:
+    if not isinstance(mapping, dict):
+        return default
+    current: Any = mapping
+    for part in path:
+        if not isinstance(current, dict):
+            return default
+        current = current.get(part, default)
+        if current is None:
+            return default
+    return current
+
+
+def _to_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"true", "1", "yes", "on"}
+    return default
+
+
+def _to_int(value: Any, default: int) -> int:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value)
+        except ValueError:
+            return default
+    return default
+
+
+def get_realtime_config(config_path: str | None = None) -> RealtimeConfig:
+    """Parse ``realtime.*`` from monkeybot.yaml, applying defaults."""
+    _, doc = load_monkeybot_yaml_dict(config_path)
+    harness_raw = doc.get("harness")
+    harness: dict[str, Any] = harness_raw if isinstance(harness_raw, dict) else {}
+    mode = str(harness.get("mode", "turn_based")).strip().lower()
+    realtime_raw = doc.get("realtime")
+    realtime: dict[str, Any] = realtime_raw if isinstance(realtime_raw, dict) else {}
+
+    return RealtimeConfig(
+        enabled=mode == "realtime",
+        websocket=RealtimeWebSocketConfig(
+            enabled=_to_bool(_nested_get(realtime, "websocket", "enabled"), default=True),
+            port=_to_int(_nested_get(realtime, "websocket", "port"), default=0) or None,
+        ),
+        audio=RealtimeAudioConfig(
+            input_format=str(_nested_get(realtime, "audio", "input_format", default="pcm_s16le_24khz_mono")),
+            output_format=str(_nested_get(realtime, "audio", "output_format", default="pcm_s16le_24khz_mono")),
+            chunk_ms=_to_int(_nested_get(realtime, "audio", "chunk_ms"), default=200),
+            max_utterance_sec=_to_int(
+                _nested_get(realtime, "audio", "max_utterance_sec"), default=60
+            ),
+        ),
+        session=RealtimeSessionConfig(
+            max_duration_sec=_to_int(
+                _nested_get(realtime, "session", "max_duration_sec"), default=1800
+            ),
+            idle_timeout_sec=_to_int(
+                _nested_get(realtime, "session", "idle_timeout_sec"), default=120
+            ),
+            max_response_turn_sec=_to_int(
+                _nested_get(realtime, "session", "max_response_turn_sec"), default=300
+            ),
+            max_concurrent_sessions=_to_int(
+                _nested_get(realtime, "session", "max_concurrent_sessions"), default=100
+            ),
+        ),
+        metrics=RealtimeMetricsConfig(
+            emit_summary_on_close=_to_bool(
+                _nested_get(realtime, "metrics", "emit_summary_on_close"), default=True
+            ),
+        ),
+        model=RealtimeModelConfig(
+            name=_nested_get(realtime, "model", "name"),
+            provider=_nested_get(realtime, "model", "provider"),
+        ),
+    )
+
+
+__all__ = [
+    "RealtimeAudioConfig",
+    "RealtimeConfig",
+    "RealtimeMetricsConfig",
+    "RealtimeModelConfig",
+    "RealtimeSessionConfig",
+    "RealtimeWebSocketConfig",
+    "get_realtime_config",
+]