runspace-agent 0.1.0__py3-none-any.whl

runspace_agent/__init__.py

@@ -0,0 +1,30 @@
+"""runspace_agent — Sandboxed execution environment for AI agents.
+
+Provides a simple interface for running AI agents that operate on
+filesystem directories: an **editable** directory (the agent's output)
+and a **read-only context** directory (traces, domain knowledge, etc.).
+
+Quick start::
+
+    from runspace_agent import RunspaceSession, run_agent
+
+    result = await run_agent(RunspaceSession(
+        editable_dir=Path("./my_skill"),
+        context_dir=Path("./context"),
+        prompt="Improve the skill based on the traces.",
+    ))
+"""
+
+from runspace_agent.agents.base import AgentResult, FilesystemAgent, Workspace
+from runspace_agent.core import RunspaceResult, RunspaceSession, run_agent
+from runspace_agent.skills import Skill
+
+__all__ = [
+    "AgentResult",
+    "FilesystemAgent",
+    "RunspaceResult",
+    "RunspaceSession",
+    "Skill",
+    "Workspace",
+    "run_agent",
+]

runspace_agent/_docker/Dockerfile

@@ -0,0 +1,38 @@
+# Build recipe for the runspace-agent:latest image.
+#
+# This Dockerfile is shipped inside the wheel (declared as package-data) so it
+# travels with any install — editable, git, or wheel. It is NOT meant to be built
+# from a repo checkout with `docker build .`; the build context is assembled at
+# runtime by runspace_agent.cli (_prepare_build_context), which lays out:
+#
+#   ./requirements.txt      runtime deps (base + the [claude] extra)
+#   ./runspace_agent/       the installed package source tree
+#
+# The image is built automatically by `runspace-srv` (or `--rebuild`).
+FROM python:3.11-slim
+
+# System deps + Node.js (required for the Claude Code runtime)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl jq && \
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Install Claude Code CLI globally
+RUN npm install -g @anthropic-ai/claude-code
+
+# Install Python deps, then drop in the package source (PYTHONPATH instead of a
+# pip install, so no pyproject.toml is needed in the build context)
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY runspace_agent/ ./runspace_agent/
+ENV PYTHONPATH=/app
+
+# Create non-root user (Claude Code refuses --dangerously-skip-permissions as root)
+RUN useradd -m -s /bin/bash agent && \
+    mkdir -p /workspace && chown agent:agent /workspace
+
+USER agent
+WORKDIR /workspace
+ENTRYPOINT ["python", "-m", "runspace_agent.entrypoint"]

runspace_agent/agents/__init__.py

@@ -0,0 +1,61 @@
+"""Agent abstractions and implementations for runspace_agent."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from runspace_agent.agents.base import AgentResult, FilesystemAgent, Workspace
+
+__all__ = [
+    "AgentResult",
+    "FilesystemAgent",
+    "Workspace",
+    "build_agent_options",
+    "create_agent",
+    "create_default_agent",
+]
+
+_AGENT_REGISTRY: dict[str, str] = {
+    "claude-code": "runspace_agent.agents.claude_code",
+}
+
+
+def _get_agent_module(agent_type: str) -> Any:
+    module_path = _AGENT_REGISTRY.get(agent_type)
+    if module_path is None:
+        available = ", ".join(sorted(_AGENT_REGISTRY))
+        raise ValueError(f"Unknown agent_type: {agent_type!r}. Available: {available}")
+    return importlib.import_module(module_path)
+
+
+def build_agent_options(
+    agent_type: str = "claude-code",
+    agent_settings: dict[str, Any] | None = None,
+) -> Any:
+    """Build agent-specific options from a freeform settings dict.
+
+    Each agent's ``build_options`` receives the full dict and reads
+    only the keys it understands.
+    """
+    mod = _get_agent_module(agent_type)
+    return mod.build_options(agent_settings)
+
+
+def create_agent(
+    agent_type: str = "claude-code",
+    options: Any = None,
+) -> FilesystemAgent:
+    """Create an agent instance of the specified type."""
+    mod = _get_agent_module(agent_type)
+    return mod.create(options)
+
+
+def create_default_agent(
+    options: Any = None,
+) -> FilesystemAgent:
+    """Create the default agent (currently :class:`ClaudeCodeAgent`).
+
+    Backward-compatible wrapper around :func:`create_agent`.
+    """
+    return create_agent(agent_type="claude-code", options=options)

runspace_agent/agents/base.py

@@ -0,0 +1,132 @@
+"""Base types for the FilesystemAgent abstraction.
+
+Defines the Protocol that any agent implementation must satisfy,
+plus the Workspace and AgentResult types used across all backends.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class Workspace:
+    """The sandboxed view that any FilesystemAgent receives.
+
+    Attributes:
+        editable_dir: Directory the agent should focus on modifying.
+        context_dir: Directory with read-only reference material
+            (traces, domain knowledge, performance history, etc.).
+        prompt: Fully constructed prompt including directory descriptions.
+        skills_dir: Path to the agent-specific skills directory, if loaded.
+        cwd: Session root directory (the agent's working directory).
+    """
+
+    editable_dir: Path
+    context_dir: Path
+    prompt: str
+    skills_dir: Path | None
+    cwd: Path
+    hooks: dict[str, list[Any]] | None = None
+
+
+@dataclass
+class AgentResult:
+    """Result returned by a FilesystemAgent after execution.
+
+    Attributes:
+        success: Whether the agent completed without errors.
+        messages: Raw messages from the agent execution (SDK-specific).
+        conversation: Serialized conversation as a list of JSON-ready dicts.
+            Each agent implementation is responsible for populating this
+            from its SDK-specific message types.
+        total_tokens: Approximate total tokens consumed.
+        duration_ms: Wall-clock execution time in milliseconds.
+        error: Error message if the agent failed, None otherwise.
+    """
+
+    success: bool
+    messages: list[Any] = field(default_factory=list)
+    conversation: list[dict[str, Any]] = field(default_factory=list)
+    total_tokens: int = 0
+    total_cost_usd: float | None = None
+    duration_ms: int = 0
+    error: str | None = None
+
+
+@runtime_checkable
+class FilesystemAgent(Protocol):
+    """Protocol for agents that operate on filesystem directories.
+
+    Any class with a ``skills_folder_name`` attribute and an async ``run``
+    method matching this signature satisfies the protocol.  This enables
+    pluggable agent backends (Claude Code, OpenCode, custom, ...) without
+    requiring inheritance.
+
+    Attributes:
+        skills_folder_name: Relative path from ``cwd`` where this agent
+            expects skills to be placed.  For example ``".claude/skills"``
+            for Claude Code or ``".opencode/skills"`` for OpenCode.
+            Used to determine where to copy user-provided skills and default skills.
+        default_skills_dir: Absolute path to the directory containing the
+            agent's bundled/preinstalled skills on disk.  Each subdirectory
+            is a separate skill.  ``None`` means the agent ships no default
+            skills.
+
+    Adding a new agent type
+    -----------------------
+    1. Create ``agents/<name>/`` with three files:
+
+       ``agent.py`` — a class satisfying this Protocol::
+
+           class MyAgent:
+               skills_folder_name: str = ".<name>/skills"
+               default_skills_dir: Path | None = ...
+
+               def __init__(self, *, options: MyAgentOptions | None = None): ...
+               async def run(self, workspace: Workspace) -> AgentResult: ...
+
+       ``options.py`` — two module-level functions the registry calls::
+
+           def build_options(
+               agent_settings: dict | None = None,
+           ) -> MyAgentOptions:
+               '''Build agent-specific options from the settings dict.
+               Read only the keys your agent understands.'''
+               ...
+
+           def create(options: Any = None) -> MyAgent:
+               '''Instantiate the agent.'''
+               ...
+
+       ``__init__.py`` — re-export everything::
+
+           from agents.<name>.agent import MyAgent
+           from agents.<name>.options import build_options, create
+
+    2. Register the agent in ``agents/__init__.py``::
+
+           _AGENT_REGISTRY: dict[str, str] = {
+               "claude-code": "runspace_agent.agents.claude_code",
+               "<name>":      "runspace_agent.agents.<name>",      # add this
+           }
+
+    That's it. The server, container, and entrypoint all resolve the agent
+    through the registry, so no changes are needed outside ``agents/``.
+    Clients select the agent by passing ``"agent_type": "<name>"`` in the
+    ``POST /run`` request body (defaults to ``"claude-code"``).
+    """
+
+    skills_folder_name: str
+    default_skills_dir: Path | None
+
+    async def run(self, workspace: Workspace) -> AgentResult:
+        """Execute the agent inside the given workspace.
+
+        The agent should read from ``workspace.context_dir``, modify files
+        in ``workspace.editable_dir``, and follow the instructions in
+        ``workspace.prompt``.
+        """
+        ...

runspace_agent/agents/claude_code/__init__.py

@@ -0,0 +1,13 @@
+"""Claude Code agent implementation."""
+
+from runspace_agent.agents.claude_code.agent import ClaudeCodeAgent
+from runspace_agent.agents.claude_code.env import ClaudeModel, build_claude_env
+from runspace_agent.agents.claude_code.options import build_options, create
+
+__all__ = [
+    "ClaudeCodeAgent",
+    "ClaudeModel",
+    "build_claude_env",
+    "build_options",
+    "create",
+]

runspace_agent/agents/claude_code/agent.py

@@ -0,0 +1,171 @@
+"""ClaudeCodeAgent -- FilesystemAgent implementation using the Claude Agent SDK.
+
+Requires the optional ``claude-code-sdk`` dependency::
+
+    uv pip install runspace-agent[claude]
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from runspace_agent.agents.base import AgentResult, Workspace
+from runspace_agent.agents.claude_code.defaults import (
+    DEFAULT_ALLOWED_TOOLS,
+    DEFAULT_DISALLOWED_TOOLS,
+    DEFAULT_MAX_TURNS,
+    DEFAULT_SYSTEM_PROMPT,
+)
+
+if TYPE_CHECKING:
+    from claude_code_sdk import ClaudeCodeOptions
+
+
+class ClaudeCodeAgent:
+    """Run a Claude Code agent inside a :class:`Workspace`.
+
+    This is the built-in :class:`~runspace_agent.agents.base.FilesystemAgent`
+    implementation backed by the Claude Agent SDK.
+
+    Users pass a :class:`~claude_code_sdk.ClaudeCodeOptions` object to
+    configure the agent.  The agent **enforces** the following fields
+    regardless of what the user sets:
+
+    * ``permission_mode`` → ``"bypassPermissions"`` (headless container)
+    * ``cwd`` → from the workspace (sandbox boundary)
+    * ``system_prompt`` → headless system prompt (no interactive prompts)
+    * ``disallowed_tools`` → interactive/scheduling tools disabled for headless
+    * ``hooks`` → from the workspace (sandbox enforcement)
+
+    If the user does not set ``allowed_tools`` or ``max_turns``, sensible
+    defaults are applied.
+
+    Parameters:
+        options: A :class:`~claude_code_sdk.ClaudeCodeOptions` instance.
+            When ``None``, a bare default is created at run time.
+    """
+
+    skills_folder_name: str = ".claude/skills"
+
+    # Repo-root-relative path to bundled skills.  Computed once at module load.
+    _DEFAULT_SKILLS_DIR: Path = (
+        Path(__file__).resolve().parent.parent.parent.parent.parent / ".claude" / "skills"
+    )
+
+    def __init__(self, options: ClaudeCodeOptions | None = None) -> None:
+        self._user_options = options
+        self.default_skills_dir: Path | None = self._DEFAULT_SKILLS_DIR
+
+    async def run(self, workspace: Workspace) -> AgentResult:
+        """Execute the Claude Code agent inside *workspace*."""
+        query, ClaudeCodeOptions = self._import_sdk()
+        options = self._build_effective_options(ClaudeCodeOptions, workspace)
+        return await self._run_agent(query, options, workspace)
+
+    def _build_effective_options(
+        self,
+        ClaudeCodeOptions: type,
+        workspace: Workspace,
+    ) -> Any:
+        """Merge user options with enforced sandbox overrides.
+
+        Priority (highest to lowest):
+        1. Enforced fields (always override, non-negotiable)
+        2. User-provided fields (from self._user_options)
+        3. Sensible defaults (only if user left field at dataclass default)
+        """
+        base = self._user_options if self._user_options is not None else ClaudeCodeOptions()
+
+        overrides: dict[str, Any] = {}
+
+        # Defaults: fill in only if user did not set them
+        if not base.allowed_tools:
+            overrides["allowed_tools"] = list(DEFAULT_ALLOWED_TOOLS)
+
+        if base.max_turns is None:
+            overrides["max_turns"] = DEFAULT_MAX_TURNS
+
+        # Enforced fields: always override regardless of user input
+        overrides["permission_mode"] = "bypassPermissions"
+        overrides["cwd"] = str(workspace.cwd)
+        overrides["system_prompt"] = DEFAULT_SYSTEM_PROMPT
+        overrides["disallowed_tools"] = list(DEFAULT_DISALLOWED_TOOLS)
+
+        if workspace.hooks:
+            overrides["hooks"] = self._build_sdk_hooks(workspace.hooks)
+
+        return dataclasses.replace(base, **overrides)
+
+    async def _run_agent(
+        self,
+        query: Any,
+        options: Any,
+        workspace: Workspace,
+    ) -> AgentResult:
+        """Iterate the agent loop with pre-built options."""
+        messages: list[Any] = []
+        total_tokens = 0
+        total_cost_usd: float | None = None
+        start_ms = int(time.time() * 1000)
+
+        async for message in query(
+            prompt=workspace.prompt,
+            options=options,
+        ):
+            messages.append(message)
+
+            if type(message).__name__ == "ResultMessage":
+                usage = getattr(message, "usage", None)
+                if isinstance(usage, dict):
+                    total_tokens += usage.get("input_tokens", 0)
+                    total_tokens += usage.get("output_tokens", 0)
+                cost = getattr(message, "total_cost_usd", None)
+                if cost is not None:
+                    total_cost_usd = cost
+
+        from runspace_agent.agents.claude_code.serializer import serialize_messages
+
+        duration_ms = int(time.time() * 1000) - start_ms
+        return AgentResult(
+            success=True,
+            messages=messages,
+            conversation=serialize_messages(messages),
+            total_tokens=total_tokens,
+            total_cost_usd=total_cost_usd,
+            duration_ms=duration_ms,
+        )
+
+    @staticmethod
+    def _build_sdk_hooks(hooks: dict[str, list[Any]]) -> dict[str, list[Any]]:
+        """Convert intermediate hooks format to SDK HookMatcher objects."""
+        from claude_code_sdk.types import HookMatcher
+
+        sdk_hooks: dict[str, list[Any]] = {}
+        for event_name, matchers in hooks.items():
+            sdk_hooks[event_name] = [
+                HookMatcher(
+                    matcher=m["matcher"],
+                    hooks=[m["hook_fn"]],
+                )
+                for m in matchers
+            ]
+        return sdk_hooks
+
+    @staticmethod
+    def _import_sdk() -> tuple[Any, Any]:
+        """Lazily import the Claude Agent SDK.
+
+        Raises :class:`ImportError` with a helpful message when the
+        optional dependency is missing.
+        """
+        try:
+            from claude_code_sdk import ClaudeCodeOptions, query
+        except ImportError:
+            raise ImportError(
+                "ClaudeCodeAgent requires the 'claude-code-sdk' package. "
+                "Install it with:  uv pip install claude-code-sdk"
+            ) from None
+        return query, ClaudeCodeOptions

runspace_agent/agents/claude_code/defaults.py

@@ -0,0 +1,38 @@
+"""Default constants for the ClaudeCodeAgent."""
+
+DEFAULT_MAX_TURNS: int = 300
+
+DEFAULT_ALLOWED_TOOLS: list[str] = [
+    "Read",
+    "Write",
+    "Edit",
+    "Bash",
+    "Glob",
+    "Grep",
+    "Skill",
+    "WebSearch",
+    "WebFetch",
+    "Agent",
+    "LSP",
+]
+
+DEFAULT_DISALLOWED_TOOLS: list[str] = [
+    "AskUserQuestion",
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "EnterWorktree",
+    "ExitWorktree",
+    "ScheduleWakeup",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "Monitor",
+]
+
+DEFAULT_SYSTEM_PROMPT: str = (
+    "You are running headless in an automated pipeline. "
+    "There is no human available to answer questions. "
+    "Do NOT use AskHumanQuestion or any interactive prompts. "
+    "Complete the task fully and autonomously. "
+    "If you encounter ambiguity, make a reasonable decision and proceed."
+)

runspace_agent/agents/claude_code/env.py

@@ -0,0 +1,42 @@
+"""Helper for building Claude Code environment variables from the current shell.
+
+This is a convenience for the examples and manual tests in this repo — it reads
+your real ``os.environ`` to assemble the env dict passed to Claude Code. Library
+users typically don't need it: they call ``POST /run`` and pass their own
+credentials explicitly via ``agent_settings.env`` (or ``ClaudeCodeOptions.env``).
+"""
+
+from __future__ import annotations
+
+import os
+from enum import StrEnum
+
+
+class ClaudeModel(StrEnum):
+    OPUS_4_8 = "claude-opus-4-8"
+    SONNET_4_6 = "claude-sonnet-4-6"
+    HAIKU_4_5 = "claude-haiku-4-5"
+
+
+def build_claude_env(model: ClaudeModel | None = None) -> dict[str, str]:
+    """Build Claude Code env vars from the current environment.
+
+    Reads credentials/config from ``os.environ`` (with a couple of common
+    fallbacks). Callers typically drop empty values before use, e.g.
+    ``{k: v for k, v in build_claude_env().items() if v}``.
+    """
+    model_id = (
+        model.value if model else os.environ.get("ANTHROPIC_MODEL", "claude-opus-4-8")
+    )
+    return {
+        "ANTHROPIC_API_KEY": os.environ.get("ANTHROPIC_API_KEY", ""),
+        "ANTHROPIC_BASE_URL": os.environ.get("ANTHROPIC_BASE_URL", "")
+        or os.environ.get("CLAUDE_CODE_LITELLM_BASE_URL", "")
+        or os.environ.get("IBM_THIRD_PARTY_API_BASE", ""),
+        "ANTHROPIC_AUTH_TOKEN": os.environ.get("ANTHROPIC_AUTH_TOKEN", "")
+        or os.environ.get("IBM_THIRD_PARTY_API_KEY", ""),
+        "ANTHROPIC_MODEL": model_id,
+        "CLAUDE_CODE_SUBAGENT_MODEL": model_id,
+        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
+        "opusPlanEnabled": "true",
+    }

runspace_agent/agents/claude_code/options.py

@@ -0,0 +1,58 @@
+"""Claude Code agent options builder and factory."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from claude_code_sdk import ClaudeCodeOptions
+
+    from runspace_agent.agents.claude_code.agent import ClaudeCodeAgent
+
+
+def build_options(
+    agent_settings: dict[str, Any] | None = None,
+) -> ClaudeCodeOptions:
+    """Build a :class:`ClaudeCodeOptions` from a settings dict.
+
+    The dict may contain any of the following keys (all optional):
+
+    - ``env``: dict of environment variables
+    - ``model``: Claude model name
+    - ``permissions.allow`` / ``permissions.disallow``: tool lists
+    - ``max_turns``: maximum conversation turns (default 300)
+    - ``mcp_servers``: MCP server configuration
+    """
+    from claude_code_sdk import ClaudeCodeOptions
+
+    settings = agent_settings or {}
+    kwargs: dict[str, Any] = {}
+
+    env_vars = {k: str(v) for k, v in settings.get("env", {}).items()}
+    if env_vars:
+        kwargs["env"] = env_vars
+
+    model = settings.get("model")
+    if model:
+        kwargs["model"] = model
+
+    permissions = settings.get("permissions", {})
+    if permissions.get("allow"):
+        kwargs["allowed_tools"] = list(permissions["allow"])
+    if permissions.get("disallow"):
+        kwargs["disallowed_tools"] = list(permissions["disallow"])
+
+    kwargs["max_turns"] = settings.get("max_turns", 300)
+
+    mcp_servers = settings.get("mcp_servers")
+    if mcp_servers:
+        kwargs["mcp_servers"] = mcp_servers
+
+    return ClaudeCodeOptions(**kwargs)
+
+
+def create(options: Any = None) -> ClaudeCodeAgent:
+    """Create a :class:`ClaudeCodeAgent` instance."""
+    from runspace_agent.agents.claude_code.agent import ClaudeCodeAgent
+
+    return ClaudeCodeAgent(options=options)