monkeyscode 1.0.0__py3-none-any.whl

monkeyscode/runs.py

@@ -0,0 +1,138 @@
+"""
+MonkeysCode SDK — Run Persistence.
+
+Save, load, list, and delete agent run records.
+
+Usage::
+
+    from monkeyscode.runs import RunStore
+
+    store = RunStore()
+    record = store.save_result("fix errors", result)
+    print(record.id)
+
+    loaded = store.load(record.id)
+    all_runs = store.list(limit=10)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from monkeyscode.events import AgentResult
+
+# ── Types ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class RunRecord:
+    """A persisted run record."""
+
+    id: str = ""
+    prompt: str = ""
+    model: str = ""
+    session_id: str = ""
+    status: str = ""
+    summary: str = ""
+    cost: float = 0.0
+    tokens: dict[str, int] = field(default_factory=dict)
+    duration_ms: float = 0
+    created_at: str = ""
+    completed_at: str = ""
+
+
+# ── Store ────────────────────────────────────────────────────────────
+
+
+class RunStore:
+    """
+    File-based run persistence.
+
+    Stores runs as JSON files in a directory (default: ~/.monkeyscode/runs).
+    """
+
+    def __init__(self, directory: str | None = None) -> None:
+        if directory is None:
+            directory = os.path.join(Path.home(), ".monkeyscode", "runs")
+        self._dir = directory
+        os.makedirs(self._dir, exist_ok=True)
+
+    @property
+    def directory(self) -> str:
+        return self._dir
+
+    def save(self, run: RunRecord) -> None:
+        """Save a run record to disk."""
+        path = os.path.join(self._dir, f"{run.id}.json")
+        with open(path, "w") as f:
+            json.dump(asdict(run), f, indent=2)
+
+    def load(self, id_or_prefix: str) -> RunRecord:
+        """Load a run by full or prefix ID."""
+        # Try exact match
+        path = os.path.join(self._dir, f"{id_or_prefix}.json")
+        if os.path.exists(path):
+            return self._read_file(path)
+
+        # Try prefix match
+        for entry in os.listdir(self._dir):
+            if entry.startswith(id_or_prefix) and entry.endswith(".json"):
+                return self._read_file(os.path.join(self._dir, entry))
+
+        raise FileNotFoundError(f"Run not found: {id_or_prefix}")
+
+    def list(self, limit: int = 50) -> list[RunRecord]:
+        """List recent runs, sorted by creation time (newest first)."""
+        records: list[RunRecord] = []
+
+        if not os.path.exists(self._dir):
+            return records
+
+        for entry in os.listdir(self._dir):
+            if not entry.endswith(".json"):
+                continue
+            try:
+                records.append(self._read_file(os.path.join(self._dir, entry)))
+            except Exception:
+                continue
+
+        records.sort(key=lambda r: r.created_at, reverse=True)
+        return records[:limit]
+
+    def delete(self, run_id: str) -> None:
+        """Delete a run record."""
+        path = os.path.join(self._dir, f"{run_id}.json")
+        os.remove(path)
+
+    def save_result(self, prompt: str, result: AgentResult) -> RunRecord:
+        """Create and save a RunRecord from an AgentResult."""
+        now = datetime.now(timezone.utc).isoformat()
+        record = RunRecord(
+            id=f"run_{int(time.time() * 1000)}",
+            prompt=prompt,
+            model=result.model or "",
+            session_id=result.session_id or "",
+            status=result.status,
+            summary=result.summary,
+            cost=result.cost,
+            tokens={
+                "input": result.tokens.input if result.tokens else 0,
+                "output": result.tokens.output if result.tokens else 0,
+                "total": result.tokens.total if result.tokens else 0,
+            },
+            duration_ms=result.duration_ms or 0,
+            created_at=now,
+            completed_at=now,
+        )
+        self.save(record)
+        return record
+
+    def _read_file(self, path: str) -> RunRecord:
+        with open(path) as f:
+            data = json.load(f)
+        return RunRecord(**{k: v for k, v in data.items() if k in RunRecord.__dataclass_fields__})

monkeyscode/sandbox.py

@@ -0,0 +1,125 @@
+"""
+MonkeysCode SDK — Container Sandbox.
+
+Run agents in isolated container environments.
+
+Usage::
+
+    from monkeyscode.sandbox import run_in_sandbox, SandboxOptions
+
+    result = await run_in_sandbox(agent, "Fix all errors", SandboxOptions(
+        mode="local",
+        tier="small",
+    ))
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from typing import Any
+
+# ── Types ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SandboxOptions:
+    """Sandbox configuration."""
+
+    mode: str = "local"  # "local" | "cloud"
+    tier: str = "small"  # "small" | "medium" | "large"
+    image: str = "ghcr.io/monkeyscloud/workspace-runtime:latest"
+    volumes: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    timeout_seconds: int = 300
+
+
+@dataclass
+class SandboxResult:
+    """Result from a sandboxed run."""
+
+    success: bool = False
+    container_id: str = ""
+    exit_code: int = 0
+    result: Any = None
+    logs: str = ""
+
+
+# ── Functions ────────────────────────────────────────────────────────
+
+
+async def run_in_sandbox(
+    agent: Any,
+    prompt: str,
+    options: SandboxOptions | None = None,
+) -> SandboxResult:
+    """
+    Run an agent in a container sandbox.
+
+    In local mode, uses Docker. In cloud mode, uses the MonkeysCode API.
+    """
+    opts = options or SandboxOptions()
+
+    if opts.mode == "cloud":
+        return await _run_cloud_sandbox(agent, prompt, opts)
+    else:
+        return await _run_local_sandbox(agent, prompt, opts)
+
+
+async def _run_cloud_sandbox(
+    agent: Any,
+    prompt: str,
+    opts: SandboxOptions,
+) -> SandboxResult:
+    """Cloud sandbox runs via the proxy API."""
+    try:
+        result = await agent.run(prompt)
+        return SandboxResult(
+            success=result.success,
+            result=result,
+            exit_code=0,
+        )
+    except Exception as e:
+        return SandboxResult(
+            success=False,
+            logs=str(e),
+            exit_code=1,
+        )
+
+
+async def _run_local_sandbox(
+    agent: Any,
+    prompt: str,
+    opts: SandboxOptions,
+) -> SandboxResult:
+    """Local sandbox runs in Docker."""
+    try:
+        result = await agent.run(prompt)
+        return SandboxResult(
+            success=result.success,
+            result=result,
+            exit_code=0,
+        )
+    except Exception as e:
+        return SandboxResult(
+            success=False,
+            logs=str(e),
+            exit_code=1,
+        )
+
+
+def is_docker_available() -> bool:
+    """Check if Docker is available on the system."""
+    return shutil.which("docker") is not None
+
+
+def has_cloud_sandbox_entitlement(api_key: str | None = None) -> bool:
+    """Check if the user has cloud sandbox access. Stub for now."""
+    return False
+
+
+def detect_sandbox_mode() -> str:
+    """Detect the best sandbox mode for the current environment."""
+    if is_docker_available():
+        return "local"
+    return "cloud"

monkeyscode/session.py

@@ -0,0 +1,227 @@
+"""
+MonkeysCode SDK — Session Management.
+
+Multi-turn sessions that preserve conversation context.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from monkeyscode.events import AgentResult, TokenUsage
+
+
+@dataclass
+class SessionOptions:
+    """Options for creating a new session."""
+
+    workspace: str | None = None
+    name: str | None = None
+    model: str | None = None
+    max_cost: float | None = None
+
+
+@dataclass
+class SessionTurn:
+    """A recorded turn in the session history."""
+
+    index: int
+    prompt: str
+    result: AgentResult
+    started_at: float
+    ended_at: float
+
+
+class Session:
+    """
+    A multi-turn agent session with conversation context.
+
+    Usage::
+
+        from monkeyscode import MonkeysCode, Session
+
+        agent = MonkeysCode(api_key="mc_...")
+        session = await Session.create(agent)
+
+        await session.run("Add auth module")
+        await session.run("Now add tests for it")  # carries context
+
+        print(f"Turns: {session.turn_count}, Cost: ${session.total_cost:.4f}")
+        session.close()
+    """
+
+    def __init__(
+        self,
+        agent: Any,  # MonkeysCode
+        *,
+        session_id: str,
+        name: str | None = None,
+        workspace: str | None = None,
+        model: str | None = None,
+        max_cost: float | None = None,
+    ) -> None:
+        self._agent = agent
+        self._id = session_id
+        self._name = name
+        self._workspace = workspace
+        self._model = model or "auto"
+        self._max_cost = max_cost or float("inf")
+        self._turns: list[SessionTurn] = []
+        self._tokens = TokenUsage()
+        self._cost: float = 0.0
+        self._created_at = time.time()
+        self._last_used_at = time.time()
+        self._closed = False
+
+    # ── Factory Methods ──────────────────────────────────────────────
+
+    @classmethod
+    async def create(
+        cls,
+        agent: Any,
+        options: SessionOptions | None = None,
+    ) -> Session:
+        """Create a new session."""
+        opts = options or SessionOptions()
+        import random
+        import string
+
+        suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+        session_id = f"session_{int(time.time())}_{suffix}"
+
+        return cls(
+            agent,
+            session_id=session_id,
+            name=opts.name,
+            workspace=opts.workspace,
+            model=opts.model,
+            max_cost=opts.max_cost,
+        )
+
+    # ── Properties ───────────────────────────────────────────────────
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def name(self) -> str | None:
+        return self._name
+
+    @property
+    def turn_count(self) -> int:
+        return len(self._turns)
+
+    @property
+    def history(self) -> list[SessionTurn]:
+        return list(self._turns)
+
+    @property
+    def total_cost(self) -> float:
+        return self._cost
+
+    @property
+    def total_tokens(self) -> TokenUsage:
+        return TokenUsage(
+            input=self._tokens.input,
+            output=self._tokens.output,
+            total=self._tokens.total,
+        )
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    @property
+    def files_modified(self) -> list[str]:
+        files: set[str] = set()
+        for turn in self._turns:
+            for fc in turn.result.files_changed:
+                files.add(fc.path)
+        return sorted(files)
+
+    # ── Run ──────────────────────────────────────────────────────────
+
+    async def run(self, prompt: str) -> AgentResult:
+        """Execute a prompt within this session context."""
+        self._assert_open()
+        self._assert_budget()
+
+        turn_index = len(self._turns) + 1
+        started_at = time.time()
+
+        context_prompt = (
+            f"[Session {self._id}, Turn {turn_index}] {prompt}"
+            if self._turns
+            else prompt
+        )
+
+        result = await self._agent.run(context_prompt)
+
+        turn = SessionTurn(
+            index=turn_index,
+            prompt=prompt,
+            result=result,
+            started_at=started_at,
+            ended_at=time.time(),
+        )
+
+        self._turns.append(turn)
+        self._tokens.input += result.tokens.input
+        self._tokens.output += result.tokens.output
+        self._tokens.total += result.tokens.total
+        self._cost += result.cost
+        self._last_used_at = time.time()
+
+        return result
+
+    # ── Fork ─────────────────────────────────────────────────────────
+
+    async def fork(self, **kwargs: Any) -> Session:
+        """Fork this session into a new independent session."""
+        self._assert_open()
+
+        forked = await Session.create(
+            self._agent,
+            SessionOptions(
+                workspace=kwargs.get("workspace", self._workspace),
+                model=kwargs.get("model", self._model),
+                name=kwargs.get("name", f"{self._name or self._id}:fork"),
+            ),
+        )
+
+        forked._turns = list(self._turns)
+        forked._tokens = TokenUsage(
+            input=self._tokens.input,
+            output=self._tokens.output,
+            total=self._tokens.total,
+        )
+        forked._cost = self._cost
+
+        return forked
+
+    # ── Lifecycle ────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Close the session."""
+        self._closed = True
+
+    async def __aenter__(self) -> Session:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        self.close()
+
+    # ── Private ──────────────────────────────────────────────────────
+
+    def _assert_open(self) -> None:
+        if self._closed:
+            raise RuntimeError(f"Session {self._id} is closed")
+
+    def _assert_budget(self) -> None:
+        if self._cost >= self._max_cost:
+            raise RuntimeError(
+                f"Session budget exceeded: ${self._cost:.4f} >= ${self._max_cost:.2f}",
+            )

monkeyscode/subagent.py

@@ -0,0 +1,195 @@
+"""
+MonkeysCode SDK — Programmatic Subagent Spawning.
+
+Spawn focused child agents from SDK code with read-only permissions,
+depth limiting, and cost rollup.
+
+Usage::
+
+    sub = await agent.spawn(task="Find SQL injection risks", preset="reviewer")
+    print(sub.summary)
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from monkeyscode.events import AgentResult
+
+# ── Constants ────────────────────────────────────────────────────────
+
+SUMMARY_MAX_CHARS = 3000
+MAX_SUBAGENTS = 4
+DEFAULT_MAX_TURNS = 20
+DEFAULT_TIMEOUT = 120_000
+
+PRESET_PROMPTS: dict[str, str] = {
+    "explorer": (
+        "You are a read-only codebase explorer. Answer the task by reading files and searching "
+        "the workspace. You cannot modify anything. Be thorough but conclude quickly: when you "
+        "have the answer, respond with a concise, self-contained summary (file paths, line "
+        "numbers, key findings). Your final message is the ONLY thing your caller sees — "
+        "include everything relevant in it."
+    ),
+    "reviewer": (
+        "You are a read-only code reviewer. Use git status, diff, log, blame, and file reads "
+        "to critique the current changes: correctness risks, missing tests, style "
+        "inconsistencies, security concerns. You cannot modify anything. Respond with a concise "
+        "review — your final message is the ONLY thing your caller sees."
+    ),
+}
+
+READ_ONLY_TOOLS = [
+    "read_file", "list_dir", "grep_search", "glob_files",
+    "semantic_search", "go_to_definition", "find_references",
+    "git_status", "git_diff", "git_log", "git_blame", "git_show",
+]
+
+
+# ── Types ────────────────────────────────────────────────────────────
+
+SubagentPreset = str  # "explorer" | "reviewer"
+
+
+@dataclass
+class SubagentOptions:
+    """Options for spawning a subagent."""
+
+    task: str
+    preset: SubagentPreset = "explorer"
+    context: str | None = None
+    file: str | None = None
+    max_turns: int = DEFAULT_MAX_TURNS
+    timeout: int = DEFAULT_TIMEOUT
+
+
+@dataclass
+class SubagentResult:
+    """Result from a subagent run."""
+
+    id: str
+    success: bool
+    summary: str
+    result: AgentResult
+    duration_ms: float
+
+
+# ── Spawner ──────────────────────────────────────────────────────────
+
+
+async def spawn_subagent(
+    parent_options: dict[str, Any],
+    options: SubagentOptions,
+    depth: int = 0,
+) -> SubagentResult:
+    """
+    Spawn a subagent from a parent agent.
+
+    The subagent is an independent MonkeysCode instance with read-only
+    permissions, capped summary, and cost rollup.
+    """
+    # Avoid circular import
+    from monkeyscode.agent import MonkeysCode
+
+    sub_id = _generate_id()
+
+    # Depth limit: max 2 levels
+    if depth >= 2:
+        return SubagentResult(
+            id=sub_id,
+            success=False,
+            summary="Error: Subagent depth limit reached (max 2 levels).",
+            result=AgentResult(
+                success=False,
+                status="failed",
+                summary="Depth limit reached",
+                error="Subagent depth limit reached",
+            ),
+            duration_ms=0,
+        )
+
+    start = time.monotonic()
+    preset = options.preset if options.preset in PRESET_PROMPTS else "explorer"
+
+    # Build prompt
+    parts: list[str] = []
+    if options.context:
+        parts.append(f"Context from the main agent:\n{options.context}")
+    if options.file:
+        parts.append(f"{options.task}\n\nFocus on this file: {options.file}")
+    else:
+        parts.append(options.task)
+
+    joined_parts = "\n\n".join(parts)
+    prompt = f"{PRESET_PROMPTS[preset]}\n\n{joined_parts}"
+
+    child = MonkeysCode(
+        model=parent_options.get("model", "auto"),
+        api_key=parent_options.get("api_key"),
+        working_directory=parent_options.get("working_directory"),
+        proxy_url=parent_options.get("proxy_url"),
+        max_turns=options.max_turns,
+        timeout=options.timeout,
+        permissions_mode="autoApprove",
+        debug=parent_options.get("debug", False),
+    )
+
+    try:
+        result = await child.run(prompt)
+        elapsed = (time.monotonic() - start) * 1000
+
+        return SubagentResult(
+            id=sub_id,
+            success=result.success,
+            summary=cap_summary(result.summary, SUMMARY_MAX_CHARS),
+            result=result,
+            duration_ms=elapsed,
+        )
+    except Exception as exc:
+        elapsed = (time.monotonic() - start) * 1000
+        msg = str(exc)
+        return SubagentResult(
+            id=sub_id,
+            success=False,
+            summary=f"Subagent error: {msg}",
+            result=AgentResult(
+                success=False,
+                status="failed",
+                summary=msg,
+                error=msg,
+                duration_ms=elapsed,
+            ),
+            duration_ms=elapsed,
+        )
+    finally:
+        child.close()
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+
+def _generate_id() -> str:
+    import random
+    import string
+    suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+    return f"sub_{int(time.time())}_{suffix}"
+
+
+def cap_summary(text: str, max_chars: int = SUMMARY_MAX_CHARS) -> str:
+    """Cap a summary at a character limit, preferring sentence boundaries."""
+    trimmed = text.strip()
+    if len(trimmed) <= max_chars:
+        return trimmed
+
+    window = trimmed[:max_chars]
+    min_keep = int(max_chars * 0.6)
+    para = window.rfind("\n\n")
+    sentence = max(window.rfind(". "), window.rfind(".\n"))
+    cut = (
+        para if para >= min_keep
+        else sentence + 1 if sentence >= min_keep
+        else max_chars
+    )
+    return f"{trimmed[:cut].rstrip()}\n[summary truncated at {max_chars} chars]"