gdmcode 0.1.0__py3-none-any.whl

src/runtime/replay.py

@@ -0,0 +1,351 @@
+"""Session Replay Engine — runtime-003.
+
+Loads any past agent session from the event log and provides:
+- Linear step-forward/back navigation through turns
+- Fork from an arbitrary turn (new session inheriting context up to that point)
+- Side-by-side session comparison (common prefix + divergence summary)
+- Turn annotation (tag turns as good/bad/interesting for eval curation)
+- Export to OpenAI fine-tune JSONL or Anthropic prompt/completion format
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+import uuid
+
+if TYPE_CHECKING:
+    from src.memory.db import GdmDatabase
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class ReplayError(Exception):
+    """Raised when the replay engine cannot fulfil a request."""
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ReplayFrame:
+    """All data associated with one agent turn."""
+
+    event_id: str
+    turn_index: int
+    model: str
+    provider: str
+    tier: str
+    user_message: str | None
+    assistant_text: str | None
+    tool_calls: list[dict]   # from tool_call_log; include parsed args/result
+    patches: list[dict]      # from patch_log
+    cost_usd: float
+    input_tokens: int
+    output_tokens: int
+    cached_tokens: int
+    ts: str
+    annotation: str | None = None
+
+
+@dataclass
+class SessionDiff:
+    """Side-by-side comparison of two sessions."""
+
+    session_a: str
+    session_b: str
+    frames_a: list[ReplayFrame] = field(default_factory=list)
+    frames_b: list[ReplayFrame] = field(default_factory=list)
+
+    def common_prefix_length(self) -> int:
+        """Number of leading turns that share the same user_message."""
+        n = min(len(self.frames_a), len(self.frames_b))
+        for i in range(n):
+            if self.frames_a[i].user_message != self.frames_b[i].user_message:
+                return i
+        return n
+
+    def divergence_summary(self) -> dict:
+        prefix = self.common_prefix_length()
+        return {
+            "common_turns": prefix,
+            "session_a_unique_turns": len(self.frames_a) - prefix,
+            "session_b_unique_turns": len(self.frames_b) - prefix,
+            "cost_a_usd": sum(f.cost_usd for f in self.frames_a),
+            "cost_b_usd": sum(f.cost_usd for f in self.frames_b),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Main class
+# ---------------------------------------------------------------------------
+
+class SessionReplay:
+    """Interactive replay engine for a single past session."""
+
+    def __init__(self, db: "GdmDatabase", session_id: str) -> None:
+        self._db = db
+        self._session_id = session_id
+        self._frames: list[ReplayFrame] = []
+        self._cursor: int = -1   # -1 = not yet loaded
+
+    # ------------------------------------------------------------------
+    # Loading
+    # ------------------------------------------------------------------
+
+    def load_session(self) -> None:
+        """Load all turns for session_id from the event log.
+
+        Raises:
+            ReplayError: if no event log rows exist for the session.
+        """
+        raw = self._db.event_log_load_session(self._session_id)
+        if not raw:
+            raise ReplayError(
+                f"No event log found for session {self._session_id!r}. "
+                "Sessions recorded before the event log schema was deployed "
+                "cannot be replayed."
+            )
+        self._frames = [self._to_frame(r) for r in raw]
+        self._cursor = 0
+
+    # ------------------------------------------------------------------
+    # Navigation
+    # ------------------------------------------------------------------
+
+    def step_forward(self) -> ReplayFrame | None:
+        """Advance one turn; returns new frame or None if already at end."""
+        if self._cursor >= len(self._frames) - 1:
+            return None
+        self._cursor += 1
+        return self._frames[self._cursor]
+
+    def step_back(self) -> ReplayFrame | None:
+        """Go back one turn; returns new frame or None if already at start."""
+        if self._cursor <= 0:
+            return None
+        self._cursor -= 1
+        return self._frames[self._cursor]
+
+    def show_turn(self, n: int) -> ReplayFrame:
+        """Jump to turn n and return its frame.
+
+        Raises:
+            IndexError: for out-of-range n.
+        """
+        if not self._frames:
+            raise IndexError("Session not loaded; call load_session() first.")
+        if not 0 <= n < len(self._frames):
+            raise IndexError(
+                f"Turn {n} out of range [0, {len(self._frames) - 1}]"
+            )
+        self._cursor = n
+        return self._frames[n]
+
+    @property
+    def current_frame(self) -> ReplayFrame | None:
+        if self._cursor < 0 or not self._frames:
+            return None
+        return self._frames[self._cursor]
+
+    @property
+    def turn_count(self) -> int:
+        return len(self._frames)
+
+    # ------------------------------------------------------------------
+    # Fork
+    # ------------------------------------------------------------------
+
+    def fork_from(self, turn_index: int, new_session_id: str) -> str:
+        """Create a new session inheriting context up to turn N (inclusive).
+
+        Looks up the project_id from the source session, inserts a new row
+        in ``sessions``, and writes memory turns for turns 0..turn_index.
+
+        Returns:
+            new_session_id (same value passed in, for chaining).
+        """
+        if not self._frames:
+            raise ReplayError("Session not loaded; call load_session() first.")
+        if not 0 <= turn_index < len(self._frames):
+            raise IndexError(
+                f"turn_index {turn_index} out of range [0, {len(self._frames) - 1}]"
+            )
+
+        # Discover project_id from source session
+        row = self._db.execute_one(
+            "SELECT project_id FROM sessions WHERE session_id=?",
+            (self._session_id,),
+        )
+        project_id = row["project_id"] if row else "default"
+
+        now = datetime.now(timezone.utc).isoformat()
+        self._db.execute(
+            "INSERT INTO sessions (session_id, project_id, created_at, updated_at) "
+            "VALUES (?, ?, ?, ?)",
+            (new_session_id, project_id, now, now),
+        )
+
+        frames = self._frames[: turn_index + 1]
+        turns = []
+        for f in frames:
+            if f.user_message:
+                turns.append(
+                    {
+                        "role": "user",
+                        "content": f.user_message,
+                        "tokens": f.input_tokens,
+                        "tool_name": None,
+                        "tool_call_id": None,
+                        "tool_calls": None,
+                    }
+                )
+            if f.assistant_text:
+                turns.append(
+                    {
+                        "role": "assistant",
+                        "content": f.assistant_text,
+                        "tokens": f.output_tokens,
+                        "tool_name": None,
+                        "tool_call_id": None,
+                        "tool_calls": None,
+                    }
+                )
+        if turns:
+            self._db.memory_save_turns(new_session_id, turns)
+
+        return new_session_id
+
+    # ------------------------------------------------------------------
+    # Annotation
+    # ------------------------------------------------------------------
+
+    def annotate_turn(self, turn_index: int, note: str) -> None:
+        """Persist a text annotation on a turn.
+
+        Stored in the ``annotation`` column of ``session_events`` and kept in
+        sync with the in-memory frame.
+        """
+        frame = self.show_turn(turn_index)
+        self._db.execute(
+            "UPDATE session_events SET annotation=? WHERE event_id=?",
+            (note, frame.event_id),
+        )
+        self._frames[turn_index].annotation = note
+
+    # ------------------------------------------------------------------
+    # Compare
+    # ------------------------------------------------------------------
+
+    def compare(self, other_session_id: str) -> SessionDiff:
+        """Return a side-by-side diff against another session."""
+        other_raw = self._db.event_log_load_session(other_session_id)
+        other_frames = [self._to_frame(r) for r in other_raw]
+        return SessionDiff(
+            session_a=self._session_id,
+            session_b=other_session_id,
+            frames_a=list(self._frames),
+            frames_b=other_frames,
+        )
+
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    def export(self, fmt: str = "openai") -> list[dict]:
+        """Export session as a list of training examples.
+
+        Args:
+            fmt: ``"openai"`` (messages array), ``"anthropic"``
+                 (prompt/completion), or ``"raw"`` (full frame dicts).
+
+        Raises:
+            ValueError: for unknown format strings.
+        """
+        if fmt == "openai":
+            return self._export_openai()
+        if fmt == "anthropic":
+            return self._export_anthropic()
+        if fmt == "raw":
+            return [dataclasses.asdict(f) for f in self._frames]
+        raise ValueError(
+            f"Unknown export format {fmt!r}. Use 'openai', 'anthropic', or 'raw'."
+        )
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _to_frame(raw: dict) -> ReplayFrame:
+        return ReplayFrame(
+            event_id=raw["event_id"],
+            turn_index=raw["turn_index"],
+            model=raw["model"],
+            provider=raw["provider"],
+            tier=raw["tier"],
+            user_message=raw.get("user_message"),
+            assistant_text=raw.get("assistant_text"),
+            tool_calls=raw.get("tool_calls") or [],
+            patches=raw.get("patches") or [],
+            cost_usd=raw.get("cost_usd") or 0.0,
+            input_tokens=raw.get("input_tokens") or 0,
+            output_tokens=raw.get("output_tokens") or 0,
+            cached_tokens=raw.get("cached_tokens") or 0,
+            ts=raw.get("ts") or "",
+            annotation=raw.get("annotation"),
+        )
+
+    def _export_openai(self) -> list[dict]:
+        """OpenAI fine-tune format: one dict per turn with a 'messages' list."""
+        records = []
+        for frame in self._frames:
+            messages = []
+            if frame.user_message:
+                messages.append({"role": "user", "content": frame.user_message})
+            for tc in frame.tool_calls:
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": None,
+                        "tool_calls": [
+                            {
+                                "id": tc.get("call_id", ""),
+                                "type": "function",
+                                "function": {
+                                    "name": tc.get("tool_name", ""),
+                                    "arguments": json.dumps(tc.get("args", {})),
+                                },
+                            }
+                        ],
+                    }
+                )
+                if tc.get("result") is not None:
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tc.get("call_id", ""),
+                            "content": json.dumps(tc["result"]),
+                        }
+                    )
+            if frame.assistant_text:
+                messages.append(
+                    {"role": "assistant", "content": frame.assistant_text}
+                )
+            if messages:
+                records.append({"messages": messages})
+        return records
+
+    def _export_anthropic(self) -> list[dict]:
+        """Anthropic prompt/completion format: one dict per turn."""
+        records = []
+        for frame in self._frames:
+            prompt = frame.user_message or ""
+            completion = frame.assistant_text or ""
+            records.append({"prompt": prompt, "completion": completion})
+        return records

src/sandbox/__init__.py

@@ -0,0 +1,2 @@
+from src.sandbox.hermetic import HermeticSandbox, SandboxConfig, SandboxResult, SandboxBackend
+__all__ = ["HermeticSandbox", "SandboxConfig", "SandboxResult", "SandboxBackend"]

src/sandbox/hermetic.py

@@ -0,0 +1,214 @@
+"""
+Hermetic sandbox for executing untrusted tool outputs and code snippets.
+
+Backends (in order of preference):
+  1. docker  — full container isolation (preferred)
+  2. firejail — Linux namespace sandbox (fallback)
+  3. subprocess — plain subprocess with resource limits (last resort, warns)
+
+The sandbox intercepts shell_exec and run_code tool calls when enabled.
+"""
+from __future__ import annotations
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+
+class SandboxBackend(str, Enum):
+    DOCKER = "docker"
+    FIREJAIL = "firejail"
+    SUBPROCESS = "subprocess"  # last resort
+
+
+@dataclass
+class SandboxConfig:
+    backend: SandboxBackend = SandboxBackend.DOCKER
+    timeout_seconds: int = 30
+    max_memory_mb: int = 512
+    max_cpu_seconds: int = 10
+    allow_network: bool = False
+    allow_write_paths: list[str] = field(default_factory=list)
+    docker_image: str = "python:3.12-slim"
+    read_only_root: bool = True
+    # Security flags
+    no_new_privs: bool = True
+    drop_caps: bool = True
+
+
+@dataclass
+class SandboxResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    timed_out: bool = False
+    oom_killed: bool = False
+    backend_used: SandboxBackend = SandboxBackend.SUBPROCESS
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out and not self.oom_killed
+
+
+class SandboxUnavailableError(Exception):
+    pass
+
+
+class HermeticSandbox:
+    def __init__(self, config: SandboxConfig = None):
+        self._config = config or SandboxConfig()
+        self._backend = self._detect_backend()
+
+    def _detect_backend(self) -> SandboxBackend:
+        requested = self._config.backend
+        if requested == SandboxBackend.DOCKER and shutil.which("docker"):
+            # Verify docker daemon is accessible
+            try:
+                r = subprocess.run(["docker", "info"], capture_output=True, timeout=5)
+                if r.returncode == 0:
+                    return SandboxBackend.DOCKER
+            except Exception:
+                pass
+            log.warning("Docker requested but daemon not available; falling back.")
+        if requested in (SandboxBackend.DOCKER, SandboxBackend.FIREJAIL):
+            if shutil.which("firejail") and platform.system() == "Linux":
+                return SandboxBackend.FIREJAIL
+        log.warning(
+            "No isolation backend available. Using plain subprocess — NOT production-safe."
+        )
+        return SandboxBackend.SUBPROCESS
+
+    def run(self, command: str, stdin_data: str = "",
+            working_dir: Optional[Path] = None) -> SandboxResult:
+        backend = self._backend
+        if backend == SandboxBackend.DOCKER:
+            return self._run_docker(command, stdin_data, working_dir)
+        if backend == SandboxBackend.FIREJAIL:
+            return self._run_firejail(command, stdin_data, working_dir)
+        return self._run_subprocess(command, stdin_data, working_dir)
+
+    def run_python(self, code: str) -> SandboxResult:
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
+            f.write(code)
+            script = f.name
+        try:
+            return self.run(f"python {script}")
+        finally:
+            try:
+                os.unlink(script)
+            except Exception:
+                pass
+
+    def _run_docker(self, command: str, stdin_data: str,
+                    working_dir: Optional[Path]) -> SandboxResult:
+        cfg = self._config
+        docker_args = [
+            "docker", "run", "--rm",
+            "--network", "none" if not cfg.allow_network else "bridge",
+            "--memory", f"{cfg.max_memory_mb}m",
+            "--cpus", "1",
+            "--pids-limit", "64",
+            "--ulimit", f"cpu={cfg.max_cpu_seconds}",
+            "--read-only" if cfg.read_only_root else None,
+            "--security-opt", "no-new-privileges" if cfg.no_new_privs else None,
+        ]
+        if working_dir:
+            docker_args += ["-v", f"{working_dir}:/workspace:ro", "-w", "/workspace"]
+        docker_args = [a for a in docker_args if a is not None]
+        docker_args += [cfg.docker_image, "sh", "-c", command]
+        return self._exec(docker_args, stdin_data, cfg.timeout_seconds,
+                          SandboxBackend.DOCKER)
+
+    def _run_firejail(self, command: str, stdin_data: str,
+                      working_dir: Optional[Path]) -> SandboxResult:
+        cfg = self._config
+        fj_args = [
+            "firejail", "--quiet", "--private",
+            "--noprofile",
+            "--no3d", "--nogroups",
+        ]
+        if not cfg.allow_network:
+            fj_args.append("--net=none")
+        fj_args += ["sh", "-c", command]
+        return self._exec(fj_args, stdin_data, cfg.timeout_seconds,
+                          SandboxBackend.FIREJAIL)
+
+    def _run_subprocess(self, command: str, stdin_data: str,
+                        working_dir: Optional[Path]) -> SandboxResult:
+        """Plain subprocess with basic resource limits (POSIX only)."""
+        cfg = self._config
+
+        def _preexec():
+            if platform.system() != "Windows":
+                try:
+                    import resource
+                    resource.setrlimit(resource.RLIMIT_CPU,
+                                       (cfg.max_cpu_seconds, cfg.max_cpu_seconds))
+                    mem_bytes = cfg.max_memory_mb * 1024 * 1024
+                    resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))
+                except Exception:
+                    pass
+
+        try:
+            proc = subprocess.Popen(
+                ["sh", "-c", command] if platform.system() != "Windows"
+                else ["cmd", "/c", command],
+                stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                cwd=str(working_dir) if working_dir else None,
+                preexec_fn=_preexec if platform.system() != "Windows" else None,
+            )
+            try:
+                stdout, stderr = proc.communicate(
+                    input=stdin_data.encode() if stdin_data else None,
+                    timeout=cfg.timeout_seconds
+                )
+                return SandboxResult(
+                    stdout=stdout.decode(errors="replace"),
+                    stderr=stderr.decode(errors="replace"),
+                    exit_code=proc.returncode,
+                    backend_used=SandboxBackend.SUBPROCESS,
+                )
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.communicate()
+                return SandboxResult("", "TIMEOUT", -1, timed_out=True,
+                                     backend_used=SandboxBackend.SUBPROCESS)
+        except Exception as e:
+            return SandboxResult("", str(e), -1,
+                                 backend_used=SandboxBackend.SUBPROCESS)
+
+    def _exec(self, args: list[str], stdin_data: str, timeout: int,
+              backend: SandboxBackend) -> SandboxResult:
+        try:
+            proc = subprocess.Popen(
+                args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            try:
+                stdout, stderr = proc.communicate(
+                    input=stdin_data.encode() if stdin_data else None,
+                    timeout=timeout
+                )
+                return SandboxResult(
+                    stdout=stdout.decode(errors="replace"),
+                    stderr=stderr.decode(errors="replace"),
+                    exit_code=proc.returncode,
+                    backend_used=backend,
+                )
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.communicate()
+                return SandboxResult("", "TIMEOUT", -1, timed_out=True,
+                                     backend_used=backend)
+        except FileNotFoundError as e:
+            raise SandboxUnavailableError(f"Backend binary not found: {e}")
+        except Exception as e:
+            return SandboxResult("", str(e), -1, backend_used=backend)

src/sandbox/policy.py

@@ -0,0 +1,44 @@
+"""Sandbox execution policy: which tool calls should be sandboxed."""
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+from src.sandbox.hermetic import HermeticSandbox, SandboxConfig, SandboxBackend
+
+
+@dataclass
+class SandboxPolicy:
+    enabled: bool = False
+    sandbox_tool_calls: list[str] = None  # None = all tool calls
+    bypass_for_autonomy_level: int = 5   # L5 admin bypass
+    config: SandboxConfig = None
+
+    def __post_init__(self):
+        if self.sandbox_tool_calls is None:
+            self.sandbox_tool_calls = ["shell_exec", "run_code", "python_repl"]
+        if self.config is None:
+            self.config = SandboxConfig()
+
+    def should_sandbox(self, tool_name: str, autonomy_level: int = 0) -> bool:
+        if not self.enabled:
+            return False
+        if autonomy_level >= self.bypass_for_autonomy_level:
+            return False
+        return tool_name in self.sandbox_tool_calls
+
+
+_global_policy: Optional[SandboxPolicy] = None
+_global_sandbox: Optional[HermeticSandbox] = None
+
+
+def set_sandbox_policy(policy: SandboxPolicy) -> None:
+    global _global_policy, _global_sandbox
+    _global_policy = policy
+    _global_sandbox = HermeticSandbox(policy.config) if policy.enabled else None
+
+
+def get_sandbox() -> Optional[HermeticSandbox]:
+    return _global_sandbox
+
+
+def get_policy() -> Optional[SandboxPolicy]:
+    return _global_policy

src/sdk/__init__.py

@@ -0,0 +1,3 @@
+from src.sdk.plugin_base import GdmPlugin, tool, provider, PermissionManifest
+
+__all__ = ["GdmPlugin", "tool", "provider", "PermissionManifest"]

src/sdk/plugin_base.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class PermissionManifest:
+    file_read: bool = True
+    file_write: bool = False
+    network: bool = False
+    git_read: bool = True
+    git_write: bool = False
+
+
+class GdmPlugin:
+    name: str = ""
+    version: str = "0.0.0"
+    permissions: PermissionManifest = field(default_factory=PermissionManifest)
+
+    def on_load(self, context: dict) -> None:
+        pass
+
+    def on_unload(self) -> None:
+        pass
+
+
+def tool(name: str, description: str, permissions: Optional[PermissionManifest] = None):
+    """Decorator to register a function as a gdm tool."""
+    def decorator(fn: Callable) -> Callable:
+        fn._gdm_tool = {"name": name, "description": description, "permissions": permissions}
+        return fn
+    return decorator
+
+
+def provider(name: str):
+    """Decorator to register a class as a model provider."""
+    def decorator(cls):
+        cls._gdm_provider = {"name": name}
+        return cls
+    return decorator