Initial commit

.dockerignore

@@ -0,0 +1,9 @@
+__pycache__
+*.pyc
+*.pyo
+.git
+.gitignore
+*.md
+outputs/
+.env
+.venv

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml /app/
+RUN pip install --no-cache-dir fastapi uvicorn[standard] pydantic websockets openai requests
+
+# Copy environment code
+COPY . /app/incident_env/
+
+# Set Python path
+ENV PYTHONPATH=/app
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+
+EXPOSE 8000
+
+CMD ["uvicorn", "incident_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,193 @@
+---
+title: SRE Incident Response Simulator
+emoji: 🚨
+colorFrom: red
+colorTo: gray
+sdk: docker
+app_port: 8000
+pinned: false
+---
+
+# 🚨 SRE Incident Response Simulator
+
+An OpenEnv environment where AI agents must diagnose and remediate production incidents across a simulated microservices architecture.
+
+## Why This Environment Matters
+
+This is a **POMDP** (Partially Observable Markov Decision Process). The agent never sees the root cause — it sees _symptoms_: climbing memory metrics, cascading error logs, firing alerts. It must gather evidence, form hypotheses, and act — exactly like a real SRE at 3 AM.
+
+| Dimension | Detail |
+|-----------|--------|
+| **Observation** | Alerts, metric timeseries, structured logs, dependency graphs, deploy history |
+| **Action space** | 10 hierarchical action types × 7 target services = rich combinatorics |
+| **Difficulty** | Easy (single-service leak) → Medium (cascading failure) → Hard (distributed deadlock) |
+| **Reward** | Oracle-shaped per-step signal for training + oracle-independent grader for evaluation |
+| **Realism** | Reactive simulation — memory climbs over time, cascades propagate, restarts don't fix root causes |
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    SIMULATED INFRASTRUCTURE                      │
+│                                                                  │
+│   ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐ │
+│   │ API GW  │────►│ Auth    │────►│ Orders  │────►│ Payment │ │
+│   └────┬────┘     └─────────┘     └────┬────┘     └────┬────┘ │
+│        │                               │                │      │
+│        ▼                               ▼                ▼      │
+│   ┌─────────┐                    ┌─────────┐     ┌─────────┐  │
+│   │ Cache   │                    │   DB    │     │ Queue   │  │
+│   └─────────┘                    └─────────┘     └─────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+7 services with reactive metrics, logs, alerts, and dependency-aware cascade propagation.
+
+---
+
+## Action Space (Hierarchical)
+
+### Level 1: Action Type
+
+| Action | Category | Description |
+|--------|----------|------------|
+| `view_alerts` | Diagnostic | See all firing alerts |
+| `query_logs` | Diagnostic | Query service logs (with level/keyword filters) |
+| `check_metrics` | Diagnostic | Get 30-minute metric timeseries |
+| `check_dependencies` | Diagnostic | View upstream/downstream dependency map |
+| `check_deploy_history` | Diagnostic | Recent deploys for a service |
+| `run_health_check` | Diagnostic | Ping a service for status |
+| `restart_service` | Remediation | Restart (fixes symptoms temporarily, not root cause) |
+| `rollback_deploy` | Remediation | Rollback to previous deploy version |
+| `scale_service` | Remediation | Scale replicas up/down |
+| `declare_root_cause` | Terminal | Submit diagnosis — ends episode |
+
+### Level 2: Target Service + Parameters
+Targeted actions require `target_service` from: `api_gateway`, `auth`, `orders`, `payment`, `cache`, `database`, `queue`.
+
+### Action Masking
+The observation includes `valid_actions[]` — illegal actions (e.g., rollback on a service with no deploy history) are rejected with a penalty.
+
+---
+
+## Observation Space (POMDP)
+
+The agent **never** sees: `fault_type`, `is_bad` deploy flag, or internal simulation state.
+
+It **does** see:
+- **Incident summary** and severity
+- **Service statuses** (healthy/degraded/down)
+- **Active alert count**
+- **Action result** (data from the last action: logs, metrics, alerts, etc.)
+- **Valid actions** (action mask)
+- **Time elapsed / budget** (SLA pressure)
+- **Cumulative reward** and step count
+
+---
+
+## Tasks
+
+| Task | Description | Difficulty | Root Cause |
+|------|-------------|-----------|------------|
+| `memory_leak` | Orders service OOM from bad deploy | Easy | Rollback orders deploy v2.3.1 |
+| `cascading_failure` | Auth config change cascading to API GW + orders | Medium | Rollback auth deploy, restart dependents |
+| `distributed_deadlock` | Payment retry change creates circular wait | Hard | Rollback payment, scale queue, restart orders |
+
+---
+
+## Reward Design (Two-Layer)
+
+### Layer 1: Per-Step Training Rewards (Oracle-Shaped)
+These rewards peek at hidden state to guide RL training:
+
+| Action Category | Condition | Reward |
+|----------------|-----------|--------|
+| Diagnostic | Investigating involved service | +0.15 |
+| Diagnostic | Investigating uninvolved service | +0.05 |
+| Any | Repeating a previous action | -0.05 |
+| Remediation | Correct target (root cause service) | +0.30 |
+| Remediation | Helpful (affected, not root cause) | +0.10 |
+| Remediation | Harmful (healthy service) | -0.15 |
+| Declaration | Correct root cause | +0.40 |
+| Declaration | Wrong root cause | -0.20 |
+| Any | Per-step efficiency penalty | -0.02 |
+| Completion | All services healthy | +0.20 |
+| Completion | Time budget exceeded | -0.10 |
+
+### Layer 2: Evaluation Grader (Oracle-Independent)
+The grader scores only the trajectory — no hidden state access:
+
+| Criterion | Weight | What it measures |
+|-----------|--------|-----------------|
+| Root cause accuracy | 40% | Did the agent declare the correct root cause? |
+| Remediation quality | 30% | Did the agent take the right fix actions? |
+| Diagnostic efficiency | 20% | Fewer steps to diagnosis = better |
+| Service restoration | 10% | Are all services healthy at episode end? |
+
+---
+
+## Quick Start
+
+### Local Development
+
+```bash
+# Install dependencies
+cd incident_env
+pip install -e .
+
+# Start server
+uvicorn incident_env.server.app:app --host 0.0.0.0 --port 8000
+
+# Test endpoints
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/reset -H "Content-Type: application/json" -d '{"task_name": "memory_leak"}'
+curl -X POST http://localhost:8000/step -H "Content-Type: application/json" -d '{"action_type": "view_alerts"}'
+```
+
+### Run Inference
+
+```bash
+export OPENAI_API_KEY=sk-...
+export MODEL_NAME=gpt-4o-mini
+export API_BASE_URL=http://localhost:8000
+
+python inference.py
+```
+
+### Docker
+
+```bash
+docker build -t incident-env -f server/Dockerfile .
+docker run -p 8000:8000 incident-env
+```
+
+---
+
+## Example Agent Interaction
+
+```
+Agent: POST /reset {"task_name": "memory_leak"}
+  → Incident triggered: "Orders service experiencing failures..."
+  → Services: orders=degraded, rest=healthy
+
+Agent: POST /step {"action_type": "view_alerts"}
+  → 3 alerts: orders HighMemoryUsage (critical), orders HighErrorRate, orders HighLatencyP99
+  → reward = +0.13
+
+Agent: POST /step {"action_type": "check_metrics", "target_service": "orders"}
+  → 30 data points: memory climbing from 35% → 78% over 20 minutes
+  → reward = +0.13
+
+Agent: POST /step {"action_type": "check_deploy_history", "target_service": "orders"}
+  → 2 deploys: v2.3.1 (20 min ago, "batch order processing") and v1.2.0
+  → reward = +0.13
+
+Agent: POST /step {"action_type": "rollback_deploy", "target_service": "orders"}
+  → "Rolled back orders from v2.3.1 to v1.2.0 — service recovering"
+  → reward = +0.28
+
+Agent: POST /step {"action_type": "declare_root_cause", "parameters": {"root_cause": "memory leak in orders caused by bad deploy v2.3.1"}}
+  → Episode done. Final grade: 0.97
+```

__init__.py

@@ -0,0 +1,32 @@
+"""
+SRE Incident Response Simulator — OpenEnv Environment.
+
+A POMDP environment where an AI agent must diagnose and remediate
+production incidents across a simulated microservices architecture.
+"""
+
+from .models import (
+    ActionType,
+    IncidentAction,
+    IncidentObservation,
+    IncidentState,
+    StepRecord,
+    AlertInfo,
+    MetricSnapshot,
+    LogEntry,
+    DeployRecord,
+    DependencyInfo,
+)
+
+__all__ = [
+    "ActionType",
+    "IncidentAction",
+    "IncidentObservation",
+    "IncidentState",
+    "StepRecord",
+    "AlertInfo",
+    "MetricSnapshot",
+    "LogEntry",
+    "DeployRecord",
+    "DependencyInfo",
+]

client.py

@@ -0,0 +1,84 @@
+"""
+EnvClient subclass for the SRE Incident Response environment.
+
+Handles WebSocket/HTTP communication with the environment server.
+Parses responses into typed models.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .models import IncidentAction, IncidentObservation, IncidentState
+
+
+class IncidentEnvClient:
+    """
+    Client for interacting with the Incident Response environment.
+
+    Can be used standalone (direct HTTP calls) or subclassed from
+    openenv.core.EnvClient for full framework integration.
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8000") -> None:
+        self.base_url = base_url.rstrip("/")
+        self._session = None
+
+    def _ensure_session(self):
+        if self._session is None:
+            import requests
+            self._session = requests.Session()
+
+    def reset(
+        self,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Reset the environment. Returns initial observation."""
+        self._ensure_session()
+        payload: Dict[str, Any] = {}
+        if task_name:
+            payload["task_name"] = task_name
+        if seed is not None:
+            payload["seed"] = seed
+
+        resp = self._session.post(f"{self.base_url}/reset", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def step(self, action: IncidentAction) -> Dict[str, Any]:
+        """Execute an action. Returns observation, reward, done."""
+        self._ensure_session()
+        payload = {
+            "action_type": action.action_type,
+            "target_service": action.target_service,
+            "parameters": action.parameters,
+        }
+        resp = self._session.post(f"{self.base_url}/step", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def state(self) -> Dict[str, Any]:
+        """Get current episode state."""
+        self._ensure_session()
+        resp = self._session.get(f"{self.base_url}/state")
+        resp.raise_for_status()
+        return resp.json()
+
+    def health(self) -> Dict[str, str]:
+        """Health check."""
+        self._ensure_session()
+        resp = self._session.get(f"{self.base_url}/health")
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        if self._session:
+            self._session.close()
+            self._session = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

inference.py

@@ -0,0 +1,313 @@
+"""
+Baseline inference script.
+
+Uses an LLM (via OpenAI-compatible API) to play through all 3 incident
+scenarios. The conversation history acts as a soft belief tracker —
+the LLM accumulates evidence across steps.
+
+stdout format: [START], [STEP], [END] blocks with exact field names
+as required by the OpenEnv automated evaluator.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import traceback
+from typing import Any, Dict, List, Optional
+
+import requests
+from openai import OpenAI
+
+
+# ------------------------------------------------------------------
+# Config
+# ------------------------------------------------------------------
+
+API_BASE_URL = os.environ.get("API_BASE_URL", "http://localhost:8000")
+MODEL_NAME = os.environ.get("MODEL_NAME", "gpt-4o-mini")
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
+MAX_STEPS = 20
+TEMPERATURE = 0.3
+
+
+# ------------------------------------------------------------------
+# System prompt — Layer 3: the LLM acts as an SRE
+# ------------------------------------------------------------------
+
+SYSTEM_PROMPT = """You are an expert Site Reliability Engineer (SRE) responding to a production incident.
+
+You are interacting with a simulated microservices infrastructure through an environment API.
+Your goal is to:
+1. DIAGNOSE the root cause of the incident
+2. REMEDIATE the issue (fix it)
+3. DECLARE the root cause when confident
+
+## Available Actions
+You must respond with a single JSON object containing your chosen action:
+
+DIAGNOSTIC (information gathering):
+- {"action_type": "view_alerts"} — See all firing alerts
+- {"action_type": "query_logs", "target_service": "<name>", "parameters": {"level": "ERROR"}} — Query logs
+- {"action_type": "check_metrics", "target_service": "<name>"} — Get metric timeseries
+- {"action_type": "check_dependencies", "target_service": "<name>"} — View dependency graph
+- {"action_type": "check_deploy_history", "target_service": "<name>"} — Recent deploys
+- {"action_type": "run_health_check", "target_service": "<name>"} — Ping a service
+
+REMEDIATION (fix actions):
+- {"action_type": "restart_service", "target_service": "<name>"} — Restart a service
+- {"action_type": "rollback_deploy", "target_service": "<name>"} — Rollback to previous deploy
+- {"action_type": "scale_service", "target_service": "<name>", "parameters": {"replicas": 5}} — Scale replicas
+
+DECLARATION:
+- {"action_type": "declare_root_cause", "parameters": {"root_cause": "<your diagnosis>"}}
+
+## Available services: api_gateway, auth, orders, payment, cache, database, queue
+
+## Strategy
+1. Start by viewing alerts to understand the scope
+2. Check metrics and logs for the most affected services
+3. Check dependency graphs to trace upstream causes
+4. Check deploy history for recently changed services
+5. Apply remediation to the root cause service FIRST
+6. Declare root cause when confident
+
+IMPORTANT: Respond with ONLY a valid JSON object. No explanation, no markdown, just the JSON action.
+"""
+
+
+# ------------------------------------------------------------------
+# Environment client (direct HTTP)
+# ------------------------------------------------------------------
+
+class EnvClient:
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+
+    def reset(self, task_name: str, seed: int = 42) -> Dict[str, Any]:
+        resp = self.session.post(f"{self.base_url}/reset", json={
+            "task_name": task_name, "seed": seed})
+        resp.raise_for_status()
+        return resp.json()
+
+    def step(self, action: Dict[str, Any]) -> Dict[str, Any]:
+        resp = self.session.post(f"{self.base_url}/step", json=action)
+        resp.raise_for_status()
+        return resp.json()
+
+    def state(self) -> Dict[str, Any]:
+        resp = self.session.get(f"{self.base_url}/state")
+        resp.raise_for_status()
+        return resp.json()
+
+
+# ------------------------------------------------------------------
+# LLM agent
+# ------------------------------------------------------------------
+
+def create_openai_client() -> OpenAI:
+    """Create OpenAI client with appropriate config."""
+    api_key = OPENAI_API_KEY or HF_TOKEN or "no-key"
+    base_url = None
+
+    # If using HF inference endpoint, set base_url
+    if HF_TOKEN and not OPENAI_API_KEY:
+        base_url = f"https://api-inference.huggingface.co/models/{MODEL_NAME}/v1"
+
+    return OpenAI(api_key=api_key, base_url=base_url)
+
+
+def parse_llm_action(response_text: str) -> Dict[str, Any]:
+    """Extract JSON action from LLM response. Handles markdown wrapping."""
+    text = response_text.strip()
+
+    # Strip markdown code fences if present
+    if text.startswith("```"):
+        lines = text.split("\n")
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        text = "\n".join(lines).strip()
+
+    # Find JSON object
+    start = text.find("{")
+    end = text.rfind("}") + 1
+    if start >= 0 and end > start:
+        return json.loads(text[start:end])
+
+    raise ValueError(f"Could not parse action from: {response_text[:200]}")
+
+
+def summarize_observation(obs: Dict[str, Any]) -> str:
+    """Convert observation dict to a readable string for the LLM context."""
+    parts = []
+    parts.append(f"Incident: {obs.get('incident_summary', 'N/A')}")
+    parts.append(f"Severity: {obs.get('severity', 'N/A')}")
+    parts.append(f"Time: {obs.get('time_elapsed_minutes', 0)}/{obs.get('time_budget_minutes', 30)} min")
+    parts.append(f"Steps: {obs.get('steps_taken', 0)}/{obs.get('max_steps', 20)}")
+    parts.append(f"Reward: {obs.get('current_reward', 0)} (cumulative: {obs.get('cumulative_reward', 0)})")
+
+    statuses = obs.get("service_statuses", {})
+    if statuses:
+        status_str = ", ".join(f"{k}: {v}" for k, v in statuses.items())
+        parts.append(f"Services: {status_str}")
+
+    parts.append(f"Alerts: {obs.get('active_alerts_count', 0)} active")
+    parts.append(f"Action result: {obs.get('action_message', 'N/A')}")
+
+    # Include action_result details (truncated)
+    action_result = obs.get("action_result", {})
+    if action_result:
+        result_str = json.dumps(action_result, indent=2, default=str)
+        if len(result_str) > 2000:
+            result_str = result_str[:2000] + "\n... (truncated)"
+        parts.append(f"Data:\n{result_str}")
+
+    return "\n".join(parts)
+
+
+def run_episode(
+    env: EnvClient,
+    llm: OpenAI,
+    task_name: str,
+    seed: int = 42,
+) -> Dict[str, Any]:
+    """Run a single episode and return results."""
+
+    # --- [START] ---
+    print(f"[START] task={task_name}")
+
+    result = env.reset(task_name, seed)
+    obs = result["observation"]
+
+    # Conversation history for belief tracking (Layer 3)
+    messages: List[Dict[str, str]] = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": f"INCIDENT TRIGGERED:\n{summarize_observation(obs)}"},
+    ]
+
+    episode_reward = 0.0
+    final_info = {}
+
+    for step_num in range(1, MAX_STEPS + 1):
+        try:
+            # Get LLM action
+            completion = llm.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=TEMPERATURE,
+                max_tokens=256,
+            )
+            llm_response = completion.choices[0].message.content or ""
+
+            # Parse action
+            action = parse_llm_action(llm_response)
+
+            # --- [STEP] ---
+            print(f"[STEP] step={step_num} action={json.dumps(action)}")
+
+            # Execute in environment
+            step_result = env.step(action)
+            obs = step_result["observation"]
+            reward = step_result.get("reward", 0.0)
+            done = step_result.get("done", False)
+            info = step_result.get("info", {})
+            episode_reward += reward
+
+            # Update conversation history (belief tracker)
+            messages.append({"role": "assistant", "content": llm_response})
+            messages.append({
+                "role": "user",
+                "content": f"Step {step_num} result (reward={reward}):\n{summarize_observation(obs)}"
+            })
+
+            if done:
+                final_info = info
+                break
+
+        except Exception as e:
+            print(f"[STEP] step={step_num} error={str(e)}", file=sys.stderr)
+            # Fallback action: view alerts
+            action = {"action_type": "view_alerts"}
+            step_result = env.step(action)
+            obs = step_result["observation"]
+            reward = step_result.get("reward", 0.0)
+            done = step_result.get("done", False)
+            episode_reward += reward
+            if done:
+                final_info = step_result.get("info", {})
+                break
+
+    # Get final state
+    final_state = env.state()
+    final_grade = final_info.get("final_grade", 0.0)
+
+    # --- [END] ---
+    print(f"[END] task={task_name} "
+          f"grade={final_grade:.3f} "
+          f"reward={episode_reward:.3f} "
+          f"steps={final_state.get('step_count', 0)}")
+
+    return {
+        "task_name": task_name,
+        "final_grade": final_grade,
+        "cumulative_reward": episode_reward,
+        "steps": final_state.get("step_count", 0),
+        "declared_root_cause": final_state.get("declared_root_cause"),
+    }
+
+
+# ------------------------------------------------------------------
+# Main
+# ------------------------------------------------------------------
+
+def main():
+    tasks = ["memory_leak", "cascading_failure", "distributed_deadlock"]
+
+    print("=" * 60)
+    print("SRE Incident Response — OpenEnv Inference")
+    print(f"Model: {MODEL_NAME}")
+    print(f"Environment: {API_BASE_URL}")
+    print("=" * 60)
+
+    env = EnvClient(API_BASE_URL)
+    llm = create_openai_client()
+
+    results = []
+    for task in tasks:
+        print(f"\n{'─' * 40}")
+        print(f"Task: {task}")
+        print(f"{'─' * 40}")
+
+        try:
+            result = run_episode(env, llm, task)
+            results.append(result)
+        except Exception as e:
+            print(f"[ERROR] Task {task} failed: {e}", file=sys.stderr)
+            traceback.print_exc()
+            results.append({
+                "task_name": task,
+                "final_grade": 0.0,
+                "cumulative_reward": 0.0,
+                "steps": 0,
+                "error": str(e),
+            })
+
+    # Summary
+    print(f"\n{'=' * 60}")
+    print("RESULTS SUMMARY")
+    print(f"{'=' * 60}")
+    for r in results:
+        print(f"  {r['task_name']:30s}  grade={r.get('final_grade', 0):.3f}  "
+              f"steps={r.get('steps', 0):2d}  "
+              f"root_cause={r.get('declared_root_cause', 'N/A')}")
+
+    avg_grade = sum(r.get("final_grade", 0) for r in results) / len(results)
+    print(f"\n  {'AVERAGE':30s}  grade={avg_grade:.3f}")
+    print(f"{'=' * 60}")
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,199 @@
+"""
+Typed models for the SRE Incident Response environment.
+
+Action space: hierarchical — select action_type first, then target + params.
+Observation space: POMDP — agent never sees fault_type, only symptoms.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Action Space (Layer 4 — Hierarchical + Masked)
+# ---------------------------------------------------------------------------
+
+class ActionType(str, Enum):
+    """Level-1 action categories — what kind of operation."""
+    VIEW_ALERTS = "view_alerts"
+    QUERY_LOGS = "query_logs"
+    CHECK_METRICS = "check_metrics"
+    CHECK_DEPENDENCIES = "check_dependencies"
+    CHECK_DEPLOY_HISTORY = "check_deploy_history"
+    RUN_HEALTH_CHECK = "run_health_check"
+    RESTART_SERVICE = "restart_service"
+    ROLLBACK_DEPLOY = "rollback_deploy"
+    SCALE_SERVICE = "scale_service"
+    DECLARE_ROOT_CAUSE = "declare_root_cause"
+
+
+# Actions that require a target_service (Level 2 — where to apply)
+TARGETED_ACTIONS = {
+    ActionType.QUERY_LOGS,
+    ActionType.CHECK_METRICS,
+    ActionType.CHECK_DEPENDENCIES,
+    ActionType.CHECK_DEPLOY_HISTORY,
+    ActionType.RUN_HEALTH_CHECK,
+    ActionType.RESTART_SERVICE,
+    ActionType.ROLLBACK_DEPLOY,
+    ActionType.SCALE_SERVICE,
+}
+
+# Actions that are diagnostic (information-gathering, no state mutation)
+DIAGNOSTIC_ACTIONS = {
+    ActionType.VIEW_ALERTS,
+    ActionType.QUERY_LOGS,
+    ActionType.CHECK_METRICS,
+    ActionType.CHECK_DEPENDENCIES,
+    ActionType.CHECK_DEPLOY_HISTORY,
+    ActionType.RUN_HEALTH_CHECK,
+}
+
+# Actions that mutate infrastructure state
+REMEDIATION_ACTIONS = {
+    ActionType.RESTART_SERVICE,
+    ActionType.ROLLBACK_DEPLOY,
+    ActionType.SCALE_SERVICE,
+}
+
+
+@dataclass
+class IncidentAction:
+    """
+    Agent action — hierarchical: action_type → target_service → parameters.
+
+    The LLM emits JSON with these three fields. The action mask in the
+    observation tells it which (action_type, target_service) pairs are legal.
+    """
+    action_type: str                            # ActionType value
+    target_service: Optional[str] = None        # Required for TARGETED_ACTIONS
+    parameters: Dict[str, Any] = field(default_factory=dict)
+
+    def parsed_type(self) -> ActionType:
+        return ActionType(self.action_type)
+
+
+# ---------------------------------------------------------------------------
+# Observation Space (Layer 2 — POMDP, partial views only)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AlertInfo:
+    """A single firing alert — what fired, not why."""
+    alert_id: str
+    severity: str           # "critical" | "warning" | "info"
+    source_service: str
+    description: str
+    firing_since: str       # ISO timestamp
+
+@dataclass
+class MetricSnapshot:
+    """Time-series metrics for a single service — temporal pattern visible."""
+    service_name: str
+    timestamps: List[str]
+    cpu_percent: List[float]
+    memory_percent: List[float]
+    error_rate_percent: List[float]
+    latency_p50_ms: List[float]
+    latency_p95_ms: List[float]
+    latency_p99_ms: List[float]
+    requests_per_sec: List[float]
+
+@dataclass
+class LogEntry:
+    """A single structured log entry — error semantics visible."""
+    timestamp: str
+    level: str              # "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL"
+    service: str
+    message: str
+    trace_id: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class DeployRecord:
+    """A single deploy — evidence trail for rollback decisions."""
+    version: str
+    timestamp: str
+    author: str
+    commit_hash: str
+    description: str
+
+@dataclass
+class DependencyInfo:
+    """Upstream/downstream dependency map for a service."""
+    service_name: str
+    depends_on: List[str]       # services this one calls
+    depended_by: List[str]      # services that call this one
+
+
+@dataclass
+class IncidentObservation:
+    """
+    What the agent sees after each step.
+
+    This is a PARTIAL observation — the agent never sees fault_type,
+    fault_target, or the internal simulation state. It must infer
+    the root cause from the five observation modalities.
+    """
+    # --- Incident context (always visible) ---
+    incident_summary: str
+    severity: str                               # "SEV1" | "SEV2" | "SEV3"
+    time_elapsed_minutes: int
+    time_budget_minutes: int
+
+    # --- Result of last action ---
+    action_result: Dict[str, Any] = field(default_factory=dict)
+    action_success: bool = True
+    action_message: str = ""
+
+    # --- Dashboard (always visible) ---
+    service_statuses: Dict[str, str] = field(default_factory=dict)  # name → "healthy"|"degraded"|"down"
+    active_alerts_count: int = 0
+
+    # --- Action mask (Layer 4 — prevents illegal actions) ---
+    valid_actions: List[str] = field(default_factory=list)
+    available_services: List[str] = field(default_factory=list)
+
+    # --- Episode progress ---
+    current_reward: float = 0.0
+    cumulative_reward: float = 0.0
+    steps_taken: int = 0
+    max_steps: int = 20
+    done: bool = False
+
+
+# ---------------------------------------------------------------------------
+# State (internal tracking — exposed via state() for debugging)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class IncidentState:
+    """Episode metadata — returned by state() for monitoring/debugging."""
+    episode_id: str = ""
+    task_name: str = ""
+    step_count: int = 0
+    time_elapsed_minutes: int = 0
+    done: bool = False
+    cumulative_reward: float = 0.0
+    declared_root_cause: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Step record — stored per step for trajectory-based grading
+# ---------------------------------------------------------------------------
+
+@dataclass
+class StepRecord:
+    """
+    Immutable record of a single step — used by the grader.
+    The grader receives List[StepRecord] and scores WITHOUT hidden state.
+    """
+    step_number: int
+    action: IncidentAction
+    reward: float
+    observation_summary: Dict[str, Any]     # key fields from observation
+    service_statuses_after: Dict[str, str]  # service health after this step
+    timestamp_minutes: int                  # simulation time

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: incident_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "incident_env"
+version = "0.1.0"
+description = "SRE Incident Response Simulator — an OpenEnv environment for training and evaluating AI agents on production incident diagnosis and remediation."
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core>=0.1.0",
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.0.0",
+    "websockets>=12.0",
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "httpx>=0.25.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["incident_env*"]

scenarios/__init__.py

@@ -0,0 +1 @@
+# Scenarios package

scenarios/base.py

@@ -0,0 +1,205 @@
+"""
+Base scenario class.
+
+Each scenario defines:
+  - How to inject faults into the infrastructure
+  - The correct root cause string
+  - Which services are involved (for reward shaping)
+  - The oracle grader (trajectory-only, no hidden state)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Set
+
+from ..simulation.infrastructure import Infrastructure
+from ..models import StepRecord
+
+
+class BaseScenario(ABC):
+    """
+    Abstract scenario.  Subclasses implement inject() and grade().
+
+    inject() mutates the infrastructure to set up the incident.
+    grade() evaluates a complete trajectory WITHOUT access to hidden state.
+    """
+
+    @property
+    @abstractmethod
+    def task_name(self) -> str:
+        """Machine-readable task identifier."""
+        ...
+
+    @property
+    @abstractmethod
+    def display_name(self) -> str:
+        """Human-readable name for display."""
+        ...
+
+    @property
+    @abstractmethod
+    def incident_summary(self) -> str:
+        """Opening summary shown to the agent at reset."""
+        ...
+
+    @property
+    @abstractmethod
+    def severity(self) -> str:
+        """SEV1/SEV2/SEV3."""
+        ...
+
+    @property
+    @abstractmethod
+    def correct_root_cause(self) -> str:
+        """The canonical root cause string (for grading)."""
+        ...
+
+    @property
+    @abstractmethod
+    def involved_services(self) -> Set[str]:
+        """Services that are actually part of the incident (for reward shaping)."""
+        ...
+
+    @property
+    @abstractmethod
+    def root_cause_service(self) -> str:
+        """The primary service where the fault originates."""
+        ...
+
+    @property
+    @abstractmethod
+    def correct_remediation_actions(self) -> List[Dict[str, str]]:
+        """List of {action_type, target_service} that constitute correct remediation."""
+        ...
+
+    @property
+    def root_cause_keywords(self) -> List[str]:
+        """Keywords that must appear in a correct root cause declaration."""
+        return []
+
+    @property
+    def time_budget_minutes(self) -> int:
+        return 30
+
+    @property
+    def max_steps(self) -> int:
+        return 20
+
+    @abstractmethod
+    def inject(self, infra: Infrastructure) -> None:
+        """
+        Inject faults into the infrastructure.
+        Called once at reset time.
+        """
+        ...
+
+    # ---------------------------------------------------------------
+    # Grading — oracle-independent, trajectory-only (Layer 6)
+    # ---------------------------------------------------------------
+
+    def grade(self, trajectory: List[StepRecord]) -> float:
+        """
+        Grade the complete trajectory.
+        Returns float in [0.0, 1.0].
+
+        This function receives ONLY the step records — no hidden state,
+        no infrastructure reference. This is critical: the evaluation
+        harness must be able to call this on a saved trajectory.
+        """
+        score = 0.0
+        score += self._grade_root_cause(trajectory)        # 0.00 – 0.40
+        score += self._grade_remediation(trajectory)        # 0.00 – 0.30
+        score += self._grade_efficiency(trajectory)         # 0.00 – 0.20
+        score += self._grade_restoration(trajectory)        # 0.00 – 0.10
+        return max(0.0, min(1.0, score))
+
+    def _grade_root_cause(self, trajectory: List[StepRecord]) -> float:
+        """
+        Did the agent correctly declare the root cause?
+        Full credit (0.40) for correct, partial credit for close.
+        """
+        declarations = [
+            s for s in trajectory
+            if s.action.action_type == "declare_root_cause"
+        ]
+        if not declarations:
+            return 0.0  # Never declared — 0 points
+
+        # Use the LAST declaration
+        declared = declarations[-1].action.parameters.get("root_cause", "").lower()
+
+        # Check keyword match
+        keywords = self.root_cause_keywords
+        if not keywords:
+            keywords = self.correct_root_cause.lower().split()
+
+        matched = sum(1 for kw in keywords if kw in declared)
+        match_ratio = matched / len(keywords) if keywords else 0
+
+        if match_ratio >= 0.6:
+            return 0.40  # Close enough — full credit
+        elif match_ratio >= 0.3:
+            return 0.20  # Partial credit
+        else:
+            return 0.0
+
+    def _grade_remediation(self, trajectory: List[StepRecord]) -> float:
+        """
+        Did the agent take the correct fix actions?
+        """
+        correct_actions = self.correct_remediation_actions
+        if not correct_actions:
+            return 0.0
+
+        taken_remediations = [
+            (s.action.action_type, s.action.target_service)
+            for s in trajectory
+            if s.action.action_type in ("restart_service", "rollback_deploy", "scale_service")
+        ]
+
+        matched = 0
+        for ca in correct_actions:
+            needed = (ca["action_type"], ca["target_service"])
+            if needed in taken_remediations:
+                matched += 1
+
+        ratio = matched / len(correct_actions)
+        return round(ratio * 0.30, 3)
+
+    def _grade_efficiency(self, trajectory: List[StepRecord]) -> float:
+        """
+        Fewer steps to reach correct diagnosis = more points.
+        Optimal path (for the scenario) gets full credit.
+        """
+        total_steps = len(trajectory)
+        if total_steps == 0:
+            return 0.0
+
+        # Generous: < 8 steps is excellent, 8-12 is good, 13-16 is okay, 17+ is bad
+        if total_steps <= 6:
+            return 0.20
+        elif total_steps <= 10:
+            return 0.15
+        elif total_steps <= 14:
+            return 0.10
+        elif total_steps <= 17:
+            return 0.05
+        else:
+            return 0.02
+
+    def _grade_restoration(self, trajectory: List[StepRecord]) -> float:
+        """
+        Are all services healthy at the end of the episode?
+        Check the LAST step's service_statuses_after.
+        """
+        if not trajectory:
+            return 0.0
+
+        final_statuses = trajectory[-1].service_statuses_after
+        if all(s == "healthy" for s in final_statuses.values()):
+            return 0.10
+        # Partial credit: how many are healthy
+        healthy_count = sum(1 for s in final_statuses.values() if s == "healthy")
+        total = len(final_statuses) if final_statuses else 1
+        return round(0.10 * (healthy_count / total), 3)

scenarios/easy_memory_leak.py

@@ -0,0 +1,126 @@
+"""
+Task 1 — Easy: Memory Leak.
+
+Single-service failure with clear metric signal and obvious recent deploy.
+Agent should: view alerts → check metrics(orders) → check deploy history →
+rollback deploy → declare root cause.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, List, Set
+
+from .base import BaseScenario
+from ..simulation.infrastructure import Infrastructure
+from ..simulation.service import Deploy
+from ..simulation.metrics import generate_memory_leak_history
+
+
+class MemoryLeakScenario(BaseScenario):
+
+    @property
+    def task_name(self) -> str:
+        return "memory_leak"
+
+    @property
+    def display_name(self) -> str:
+        return "Memory Leak — Orders Service"
+
+    @property
+    def incident_summary(self) -> str:
+        return (
+            "INCIDENT: Orders service is experiencing intermittent failures "
+            "and restarts. Customers are reporting failed checkout attempts. "
+            "The on-call SRE has been paged."
+        )
+
+    @property
+    def severity(self) -> str:
+        return "SEV2"
+
+    @property
+    def correct_root_cause(self) -> str:
+        return "memory leak in orders service caused by bad deploy v2.3.1"
+
+    @property
+    def root_cause_keywords(self) -> List[str]:
+        return ["memory", "leak", "orders", "deploy"]
+
+    @property
+    def involved_services(self) -> Set[str]:
+        return {"orders"}
+
+    @property
+    def root_cause_service(self) -> str:
+        return "orders"
+
+    @property
+    def correct_remediation_actions(self) -> List[Dict[str, str]]:
+        return [
+            {"action_type": "rollback_deploy", "target_service": "orders"},
+        ]
+
+    def inject(self, infra: Infrastructure) -> None:
+        """
+        Set up the memory leak scenario:
+        1. Add a bad deploy to orders service
+        2. Inject memory_leak fault
+        3. Populate metric history showing the leak pattern
+        4. Pre-populate some logs showing OOM symptoms
+        """
+        orders = infra.get_service("orders")
+        if not orders:
+            return
+
+        # --- Bad deploy (the root cause) ---
+        bad_deploy = Deploy(
+            version="v2.3.1",
+            timestamp_minutes=-20,  # 20 minutes ago
+            author="alice",
+            commit_hash="a1b2c3",
+            description="Feature: batch order processing with in-memory cache",
+            is_bad=True,
+        )
+        orders.deploy_history.append(bad_deploy)
+
+        # --- Inject the memory leak fault ---
+        orders.inject_fault("memory_leak", rate=1.2)
+
+        # --- Pre-populate metric history showing the leak ---
+        orders.metric_history = generate_memory_leak_history(
+            minutes=30,
+            start_minute=0,
+            leak_start_offset=10,  # leak started 20 min into the history
+            rate=1.2,
+        )
+
+        # --- Set current metrics to reflect ~20 minutes of leak ---
+        orders.memory_percent = 78.0 + random.gauss(0, 2)
+        orders.cpu_percent = 35.0 + random.gauss(0, 3)
+        orders.error_rate_percent = 12.0 + random.gauss(0, 2)
+        orders.latency_p95_ms = 350.0 + random.gauss(0, 30)
+        orders.latency_p99_ms = 800.0 + random.gauss(0, 50)
+        orders.status = "degraded"
+
+        # --- Pre-populated logs showing symptoms ---
+        base_logs = [
+            {"timestamp": "2025-01-15T14:10:00Z", "level": "INFO", "service": "orders",
+             "message": "Deploy v2.3.1 started — rolling update initiated", "trace_id": None},
+            {"timestamp": "2025-01-15T14:11:00Z", "level": "INFO", "service": "orders",
+             "message": "Deploy v2.3.1 complete — all replicas updated", "trace_id": None},
+            {"timestamp": "2025-01-15T14:18:00Z", "level": "WARN", "service": "orders",
+             "message": "GC pressure: heap usage at 62%, GC pause 340ms", "trace_id": None},
+            {"timestamp": "2025-01-15T14:22:00Z", "level": "WARN", "service": "orders",
+             "message": "GC pressure: heap usage at 71%, GC pause 580ms", "trace_id": None},
+            {"timestamp": "2025-01-15T14:25:00Z", "level": "ERROR", "service": "orders",
+             "message": "Memory allocation failed: unable to allocate 128MB for batch cache",
+             "trace_id": "trace-442918"},
+            {"timestamp": "2025-01-15T14:27:00Z", "level": "WARN", "service": "orders",
+             "message": "GC overhead limit exceeded: spent 87% of time in GC",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:28:00Z", "level": "ERROR", "service": "orders",
+             "message": "Request processing failed: OutOfMemoryError in batch order handler",
+             "trace_id": "trace-553201"},
+        ]
+        orders.logs = base_logs

scenarios/hard_distributed_deadlock.py

@@ -0,0 +1,192 @@
+"""
+Task 3 — Hard: Distributed Deadlock.
+
+A deploy to the payment service changed its retry logic to be aggressive.
+This creates a circular wait:
+  orders → payment (waiting on ack)
+  payment → queue (retrying aggressively, flooding)
+  queue → orders (backpressure, orders can't consume)
+
+No single service crashes — all three show high latency and scattered
+timeout errors.  The agent must correlate cross-service logs with trace IDs
+and check deploy history to find that payment's retry change is the root cause.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, List, Set
+
+from .base import BaseScenario
+from ..simulation.infrastructure import Infrastructure
+from ..simulation.service import Deploy
+from ..simulation.metrics import generate_high_latency_history, generate_healthy_history
+
+
+class DistributedDeadlockScenario(BaseScenario):
+
+    @property
+    def task_name(self) -> str:
+        return "distributed_deadlock"
+
+    @property
+    def display_name(self) -> str:
+        return "Distributed Deadlock — Payment/Orders/Queue Circular Wait"
+
+    @property
+    def incident_summary(self) -> str:
+        return (
+            "INCIDENT: Order processing latency has spiked dramatically. "
+            "Customers report orders 'stuck in processing' for 5+ minutes. "
+            "No single service appears to be down — all health checks pass "
+            "but with high latency. Payment confirmations are severely delayed."
+        )
+
+    @property
+    def severity(self) -> str:
+        return "SEV1"
+
+    @property
+    def correct_root_cause(self) -> str:
+        return "payment service deploy changed retry logic creating circular deadlock with orders and queue"
+
+    @property
+    def root_cause_keywords(self) -> List[str]:
+        return ["payment", "retry", "deadlock", "deploy"]
+
+    @property
+    def involved_services(self) -> Set[str]:
+        return {"orders", "payment", "queue"}
+
+    @property
+    def root_cause_service(self) -> str:
+        return "payment"
+
+    @property
+    def correct_remediation_actions(self) -> List[Dict[str, str]]:
+        return [
+            {"action_type": "rollback_deploy", "target_service": "payment"},
+            {"action_type": "scale_service", "target_service": "queue"},
+            {"action_type": "restart_service", "target_service": "orders"},
+        ]
+
+    def inject(self, infra: Infrastructure) -> None:
+        """
+        Set up distributed deadlock:
+        1. Payment gets bad deploy (aggressive retry) → circular_wait fault
+        2. Orders and queue also get circular_wait
+        3. All three show high latency but no crashes
+        4. Logs show scattered timeouts with correlated trace IDs
+        5. Red herring: cache shows a brief latency spike too
+        """
+        payment = infra.get_service("payment")
+        orders = infra.get_service("orders")
+        queue = infra.get_service("queue")
+        cache = infra.get_service("cache")
+
+        if not all([payment, orders, queue]):
+            return
+
+        # --- Bad deploy on payment (root cause) ---
+        bad_deploy = Deploy(
+            version="v3.1.0",
+            timestamp_minutes=-12,
+            author="charlie",
+            commit_hash="f7g8h9",
+            description="Improve payment reliability: increase retry count and reduce backoff",
+            is_bad=True,
+        )
+        payment.deploy_history.append(bad_deploy)
+
+        # --- Inject circular_wait on all three services ---
+        payment.inject_fault("circular_wait", peers=["queue", "orders"])
+        orders.inject_fault("circular_wait", peers=["payment"])
+        queue.inject_fault("circular_wait", peers=["orders", "payment"])
+
+        # --- High latency metric histories ---
+        payment.metric_history = generate_high_latency_history(
+            minutes=30, start_minute=0, latency_start_offset=18, target_p99=8000)
+        orders.metric_history = generate_high_latency_history(
+            minutes=30, start_minute=0, latency_start_offset=20, target_p99=6000)
+        queue.metric_history = generate_high_latency_history(
+            minutes=30, start_minute=0, latency_start_offset=19, target_p99=10000)
+
+        # --- Current metrics ---
+        for svc, p99 in [(payment, 7000), (orders, 5500), (queue, 9000)]:
+            svc.latency_p50_ms = 400 + random.gauss(0, 30)
+            svc.latency_p95_ms = p99 * 0.6 + random.gauss(0, 100)
+            svc.latency_p99_ms = p99 + random.gauss(0, 200)
+            svc.error_rate_percent = 12.0 + random.gauss(0, 3)
+            svc.requests_per_sec = max(30, 150 + random.gauss(0, 20))
+            svc.status = "degraded"
+
+        # --- Shared trace IDs to enable cross-service correlation ---
+        shared_traces = [f"trace-{random.randint(800000, 899999)}" for _ in range(5)]
+
+        # Payment logs
+        payment.logs = [
+            {"timestamp": "2025-01-15T14:18:00Z", "level": "INFO", "service": "payment",
+             "message": "Deploy v3.1.0 started — retry improvements", "trace_id": None},
+            {"timestamp": "2025-01-15T14:18:30Z", "level": "INFO", "service": "payment",
+             "message": "Deploy v3.1.0 complete — retry_count=10, backoff=100ms",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:20:00Z", "level": "WARN", "service": "payment",
+             "message": f"Retrying queue publish: attempt 5/10, waiting 100ms — {shared_traces[0]}",
+             "trace_id": shared_traces[0]},
+            {"timestamp": "2025-01-15T14:21:00Z", "level": "ERROR", "service": "payment",
+             "message": f"Timeout waiting for queue acknowledgment: blocked 12000ms",
+             "trace_id": shared_traces[1]},
+            {"timestamp": "2025-01-15T14:23:00Z", "level": "WARN", "service": "payment",
+             "message": "Thread pool: 195/200 threads blocked waiting on downstream calls",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:25:00Z", "level": "ERROR", "service": "payment",
+             "message": f"Payment processing stuck: round-trip to queue exceeded 25000ms",
+             "trace_id": shared_traces[2]},
+        ]
+
+        # Orders logs
+        orders.logs = [
+            {"timestamp": "2025-01-15T14:20:00Z", "level": "WARN", "service": "orders",
+             "message": f"Waiting on payment confirmation: no response after 8000ms",
+             "trace_id": shared_traces[0]},
+            {"timestamp": "2025-01-15T14:21:30Z", "level": "ERROR", "service": "orders",
+             "message": f"Order {random.randint(10000, 99999)} stuck in PROCESSING state: "
+                        f"payment callback not received after 15000ms",
+             "trace_id": shared_traces[1]},
+            {"timestamp": "2025-01-15T14:23:00Z", "level": "WARN", "service": "orders",
+             "message": "Cannot consume from queue: consumer threads blocked waiting on payment",
+             "trace_id": shared_traces[2]},
+            {"timestamp": "2025-01-15T14:25:00Z", "level": "ERROR", "service": "orders",
+             "message": "Timeout calling payment-service: deadline exceeded after 30000ms",
+             "trace_id": shared_traces[3]},
+        ]
+
+        # Queue logs
+        queue.logs = [
+            {"timestamp": "2025-01-15T14:20:00Z", "level": "WARN", "service": "queue",
+             "message": "Queue depth increasing: 5,420 messages pending (threshold: 1,000)",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:21:00Z", "level": "WARN", "service": "queue",
+             "message": f"Consumer lag: orders consumer 3,200 messages behind",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:22:00Z", "level": "ERROR", "service": "queue",
+             "message": f"Publish flood detected: payment-service publishing at 500 msg/s "
+                        f"(normal: 50 msg/s)", "trace_id": shared_traces[2]},
+            {"timestamp": "2025-01-15T14:24:00Z", "level": "WARN", "service": "queue",
+             "message": "Backpressure applied to orders consumer: cannot keep up with "
+                        "publish rate", "trace_id": shared_traces[3]},
+            {"timestamp": "2025-01-15T14:26:00Z", "level": "ERROR", "service": "queue",
+             "message": "Queue depth critical: 12,840 messages pending — memory pressure",
+             "trace_id": None},
+        ]
+
+        # --- Red herring: cache shows a brief latency spike ---
+        if cache:
+            cache.logs.append({
+                "timestamp": "2025-01-15T14:22:00Z", "level": "WARN", "service": "cache",
+                "message": "Redis SLOWLOG: KEYS pattern='order:pending:*' took 450ms",
+                "trace_id": None})
+            cache.logs.append({
+                "timestamp": "2025-01-15T14:24:00Z", "level": "WARN", "service": "cache",
+                "message": "Redis memory usage: 78% — evicting LRU keys",
+                "trace_id": None})

scenarios/medium_cascading_failure.py

@@ -0,0 +1,156 @@
+"""
+Task 2 — Medium: Cascading Failure.
+
+A bad configuration change to the auth service causes it to return 500s
+on every token validation request. This cascades to api_gateway and orders
+(both depend on auth). Multiple alerts fire across services — the agent
+must trace the dependency graph to find the ROOT cause is auth, not the
+downstream services showing symptoms.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, List, Set
+
+from .base import BaseScenario
+from ..simulation.infrastructure import Infrastructure
+from ..simulation.service import Deploy
+from ..simulation.metrics import generate_error_spike_history, generate_healthy_history
+
+
+class CascadingFailureScenario(BaseScenario):
+
+    @property
+    def task_name(self) -> str:
+        return "cascading_failure"
+
+    @property
+    def display_name(self) -> str:
+        return "Cascading Failure — Auth Service Configuration"
+
+    @property
+    def incident_summary(self) -> str:
+        return (
+            "INCIDENT: Multiple services are experiencing elevated error rates. "
+            "API Gateway is returning 5xx errors to external clients. "
+            "Orders and Auth services both show failures. "
+            "Customer-facing impact confirmed — payments not processing."
+        )
+
+    @property
+    def severity(self) -> str:
+        return "SEV1"
+
+    @property
+    def correct_root_cause(self) -> str:
+        return "auth service bad config deploy caused authentication failures cascading to dependents"
+
+    @property
+    def root_cause_keywords(self) -> List[str]:
+        return ["auth", "config", "deploy", "cascade"]
+
+    @property
+    def involved_services(self) -> Set[str]:
+        return {"auth", "api_gateway", "orders"}
+
+    @property
+    def root_cause_service(self) -> str:
+        return "auth"
+
+    @property
+    def correct_remediation_actions(self) -> List[Dict[str, str]]:
+        return [
+            {"action_type": "rollback_deploy", "target_service": "auth"},
+            {"action_type": "restart_service", "target_service": "api_gateway"},
+            {"action_type": "restart_service", "target_service": "orders"},
+        ]
+
+    def inject(self, infra: Infrastructure) -> None:
+        """
+        Set up cascading failure:
+        1. Auth gets a bad config deploy → high_error_rate fault
+        2. Downstream services (api_gateway, orders) get dependency_degraded
+        3. Red herrings: orders also shows some unrelated log noise
+        """
+        auth = infra.get_service("auth")
+        api_gw = infra.get_service("api_gateway")
+        orders = infra.get_service("orders")
+
+        if not all([auth, api_gw, orders]):
+            return
+
+        # --- Bad deploy on auth (the root cause) ---
+        bad_deploy = Deploy(
+            version="v1.8.0",
+            timestamp_minutes=-15,
+            author="bob",
+            commit_hash="d4e5f6",
+            description="Config update: rotate JWT signing secret",
+            is_bad=True,
+        )
+        auth.deploy_history.append(bad_deploy)
+
+        # --- Inject auth fault ---
+        auth.inject_fault("high_error_rate", rate=65.0)
+        auth.metric_history = generate_error_spike_history(
+            minutes=30, start_minute=0, spike_start_offset=15, error_rate_target=65.0)
+        auth.error_rate_percent = 65.0 + random.gauss(0, 3)
+        auth.status = "down"
+        auth.latency_p95_ms = 500 + random.gauss(0, 50)
+        auth.latency_p99_ms = 1500 + random.gauss(0, 100)
+
+        # Auth-specific logs showing the config error
+        auth.logs = [
+            {"timestamp": "2025-01-15T14:15:00Z", "level": "INFO", "service": "auth",
+             "message": "Deploy v1.8.0 started — config update: JWT secret rotation",
+             "trace_id": None},
+            {"timestamp": "2025-01-15T14:15:30Z", "level": "INFO", "service": "auth",
+             "message": "Deploy v1.8.0 complete — all replicas updated", "trace_id": None},
+            {"timestamp": "2025-01-15T14:16:00Z", "level": "ERROR", "service": "auth",
+             "message": "NullPointerException: configuration key 'auth.jwt.secret' is null",
+             "trace_id": "trace-110001"},
+            {"timestamp": "2025-01-15T14:16:15Z", "level": "ERROR", "service": "auth",
+             "message": "Token validation failed: cannot sign with null key — returning 500",
+             "trace_id": "trace-110002"},
+            {"timestamp": "2025-01-15T14:17:00Z", "level": "ERROR", "service": "auth",
+             "message": "Health check failed: auth returned HTTP 500", "trace_id": None},
+            {"timestamp": "2025-01-15T14:20:00Z", "level": "ERROR", "service": "auth",
+             "message": "Authentication failed for 180 requests in last 60s — returning HTTP 500",
+             "trace_id": None},
+        ]
+
+        # --- Cascaded impact on api_gateway ---
+        api_gw.inject_fault("dependency_degraded", upstream="auth")
+        api_gw.error_rate_percent = 45.0 + random.gauss(0, 5)
+        api_gw.latency_p95_ms = 2000 + random.gauss(0, 200)
+        api_gw.status = "degraded"
+        api_gw.logs = [
+            {"timestamp": "2025-01-15T14:17:00Z", "level": "ERROR", "service": "api_gateway",
+             "message": "Call to auth-service failed: HTTP 500 Internal Server Error — "
+                        "retrying (1/3)", "trace_id": "trace-220001"},
+            {"timestamp": "2025-01-15T14:17:30Z", "level": "ERROR", "service": "api_gateway",
+             "message": "All retry attempts to auth-service exhausted — returning 502 to client",
+             "trace_id": "trace-220002"},
+            {"timestamp": "2025-01-15T14:18:00Z", "level": "WARN", "service": "api_gateway",
+             "message": "Circuit breaker for auth-service: state=OPEN, failures=25, threshold=10",
+             "trace_id": None},
+        ]
+
+        # --- Cascaded impact on orders ---
+        orders.inject_fault("dependency_degraded", upstream="auth")
+        orders.error_rate_percent = 30.0 + random.gauss(0, 4)
+        orders.latency_p95_ms = 1800 + random.gauss(0, 150)
+        orders.status = "degraded"
+        orders.logs = [
+            {"timestamp": "2025-01-15T14:17:00Z", "level": "ERROR", "service": "orders",
+             "message": "Call to auth-service failed: HTTP 500 — cannot validate order token",
+             "trace_id": "trace-330001"},
+            {"timestamp": "2025-01-15T14:18:00Z", "level": "ERROR", "service": "orders",
+             "message": "Order creation failed: authentication service unavailable",
+             "trace_id": "trace-330002"},
+            # Red herring
+            {"timestamp": "2025-01-15T14:19:00Z", "level": "WARN", "service": "orders",
+             "message": "Database connection pool: 18/20 active connections — approaching limit",
+             "trace_id": None},
+        ]

server/__init__.py

@@ -0,0 +1 @@
+# Server package

server/app.py

@@ -0,0 +1,111 @@
+"""
+Thin FastAPI server — marshals JSON in/out.
+No simulation logic lives here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from .incident_environment import IncidentEnvironment
+
+# ------------------------------------------------------------------
+# App
+# ------------------------------------------------------------------
+
+app = FastAPI(
+    title="SRE Incident Response Environment",
+    description="An OpenEnv environment for training AI agents on production incident response.",
+    version="0.1.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+env = IncidentEnvironment()
+
+
+# ------------------------------------------------------------------
+# Request / Response models (thin wrappers)
+# ------------------------------------------------------------------
+
+class ResetRequest(BaseModel):
+    task_name: Optional[str] = None
+    seed: Optional[int] = None
+
+
+class StepRequest(BaseModel):
+    action_type: str
+    target_service: Optional[str] = None
+    parameters: Dict[str, Any] = {}
+
+
+# ------------------------------------------------------------------
+# Endpoints
+# ------------------------------------------------------------------
+
+@app.get("/health")
+def health() -> Dict[str, str]:
+    """Health check — the validator pings this first."""
+    return {"status": "healthy"}
+
+
+@app.post("/reset")
+def reset(request: ResetRequest) -> Dict[str, Any]:
+    """
+    Initialize a new incident episode.
+    POST /reset {"task_name": "memory_leak", "seed": 42}
+    """
+    result = env.reset(
+        task_name=request.task_name,
+        seed=request.seed,
+    )
+    return result
+
+
+@app.post("/step")
+def step(request: StepRequest) -> Dict[str, Any]:
+    """
+    Execute one agent action.
+    POST /step {"action_type": "view_alerts"}
+    """
+    action_data = {
+        "action_type": request.action_type,
+        "target_service": request.target_service,
+        "parameters": request.parameters,
+    }
+    result = env.step(action_data)
+    return result
+
+
+@app.get("/state")
+def state() -> Dict[str, Any]:
+    """
+    Get current episode metadata.
+    GET /state
+    """
+    return env.get_state()
+
+
+@app.get("/tasks")
+def list_tasks() -> Dict[str, Any]:
+    """List available tasks with descriptions."""
+    from ..tasks import TASK_REGISTRY
+    tasks = {}
+    for name, cls in TASK_REGISTRY.items():
+        scenario = cls()
+        tasks[name] = {
+            "display_name": scenario.display_name,
+            "severity": scenario.severity,
+            "max_steps": scenario.max_steps,
+            "time_budget_minutes": scenario.time_budget_minutes,
+        }
+    return {"tasks": tasks}

server/incident_environment.py

@@ -0,0 +1,449 @@
+"""
+Core Environment implementation.
+
+Execution order per step:  validate → mutate → tick → observe → reward.
+
+The environment uses oracle-shaped rewards for training (they peek at hidden
+state to compute whether the agent investigated the right service) but the
+grader used for evaluation is oracle-independent (trajectory-only).
+"""
+
+from __future__ import annotations
+
+import uuid
+import random
+from dataclasses import asdict
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..models import (
+    ActionType,
+    IncidentAction,
+    IncidentObservation,
+    IncidentState,
+    StepRecord,
+    DIAGNOSTIC_ACTIONS,
+    REMEDIATION_ACTIONS,
+    TARGETED_ACTIONS,
+)
+from ..simulation.infrastructure import Infrastructure, SERVICE_NAMES
+from ..tasks import get_scenario, TASK_NAMES
+from ..scenarios.base import BaseScenario
+
+
+class IncidentEnvironment:
+    """
+    SRE Incident Response Environment.
+
+    Implements the three OpenEnv methods:
+      - reset(task_name) → IncidentObservation
+      - step(action)     → dict with observation, reward, done
+      - state()          → IncidentState
+    """
+
+    def __init__(self) -> None:
+        self._infra: Optional[Infrastructure] = None
+        self._scenario: Optional[BaseScenario] = None
+        self._state = IncidentState()
+        self._trajectory: List[StepRecord] = []
+        self._cumulative_reward: float = 0.0
+        self._done: bool = False
+        self._root_cause_declared: bool = False
+
+    # ------------------------------------------------------------------
+    # reset()
+    # ------------------------------------------------------------------
+
+    def reset(
+        self,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Initialize a new incident episode.
+
+        Args:
+            task_name: One of "memory_leak", "cascading_failure", "distributed_deadlock".
+                       If None, picks randomly.
+            seed: Optional random seed for reproducibility.
+
+        Returns:
+            Dict with observation, reward=0.0, done=False.
+        """
+        if seed is not None:
+            random.seed(seed)
+
+        if task_name is None:
+            task_name = random.choice(TASK_NAMES)
+
+        # Create fresh infrastructure
+        self._infra = Infrastructure()
+        self._scenario = get_scenario(task_name)
+        self._infra.time_budget_minutes = self._scenario.time_budget_minutes
+
+        # Inject scenario faults
+        self._scenario.inject(self._infra)
+
+        # Run a few ticks to let cascades propagate
+        for _ in range(3):
+            self._infra.tick()
+
+        # Reset episode state
+        self._state = IncidentState(
+            episode_id=str(uuid.uuid4()),
+            task_name=task_name,
+            step_count=0,
+            time_elapsed_minutes=self._infra.current_minute,
+            done=False,
+            cumulative_reward=0.0,
+        )
+        self._trajectory = []
+        self._cumulative_reward = 0.0
+        self._done = False
+        self._root_cause_declared = False
+
+        obs = self._build_observation(
+            action_result={"message": "Incident triggered. Begin investigation."},
+            action_success=True,
+            action_message="Episode started",
+            reward=0.0,
+        )
+
+        return {
+            "observation": obs,
+            "reward": 0.0,
+            "done": False,
+        }
+
+    # ------------------------------------------------------------------
+    # step()  —  validate → mutate → tick → observe → reward
+    # ------------------------------------------------------------------
+
+    def step(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute one agent action.
+
+        Args:
+            action_data: Dict with action_type, target_service, parameters.
+
+        Returns:
+            Dict with observation, reward, done, info.
+        """
+        if self._done:
+            obs = self._build_observation(
+                action_result={"error": "Episode is already done."},
+                action_success=False,
+                action_message="Episode already finished",
+                reward=0.0,
+            )
+            return {"observation": obs, "reward": 0.0, "done": True, "info": {}}
+
+        if self._infra is None or self._scenario is None:
+            obs = self._build_observation(
+                action_result={"error": "Environment not initialized. Call reset() first."},
+                action_success=False,
+                action_message="Not initialized",
+                reward=0.0,
+            )
+            return {"observation": obs, "reward": 0.0, "done": False, "info": {}}
+
+        # Parse action
+        action = IncidentAction(
+            action_type=action_data.get("action_type", ""),
+            target_service=action_data.get("target_service"),
+            parameters=action_data.get("parameters", {}),
+        )
+
+        # ---- VALIDATE ----
+        is_valid, error_msg = self._infra.validate_action(
+            action.action_type, action.target_service)
+
+        if not is_valid:
+            reward = -0.05
+            self._cumulative_reward += reward
+            self._state.step_count += 1
+            obs = self._build_observation(
+                action_result={"error": error_msg},
+                action_success=False,
+                action_message=f"Invalid action: {error_msg}",
+                reward=reward,
+            )
+            self._record_step(action, reward, obs)
+            return {"observation": obs, "reward": reward, "done": False, "info": {"error": error_msg}}
+
+        # ---- MUTATE ----
+        action_result, action_msg = self._execute_action(action)
+
+        # ---- TICK ----
+        self._infra.tick()
+        self._state.step_count += 1
+        self._state.time_elapsed_minutes = self._infra.current_minute
+
+        # ---- REWARD (oracle-shaped for training) ----
+        # Must compute BEFORE recording — so repeat detection doesn't
+        # flag the current action as already taken.
+        reward = self._compute_reward(action)
+        self._infra.record_action(action.action_type, action.target_service)
+        self._cumulative_reward += reward
+        self._state.cumulative_reward = self._cumulative_reward
+
+        # ---- CHECK DONE ----
+        done = self._check_done(action)
+        self._done = done
+        self._state.done = done
+
+        # ---- OBSERVE ----
+        obs = self._build_observation(
+            action_result=action_result,
+            action_success=True,
+            action_message=action_msg,
+            reward=reward,
+        )
+
+        self._record_step(action, reward, obs)
+
+        info: Dict[str, Any] = {}
+        if done:
+            # Compute final grade (oracle-independent)
+            final_grade = self._scenario.grade(self._trajectory)
+            info["final_grade"] = final_grade
+            info["task_name"] = self._scenario.task_name
+            info["steps_taken"] = self._state.step_count
+            info["trajectory_length"] = len(self._trajectory)
+
+        return {"observation": obs, "reward": reward, "done": done, "info": info}
+
+    # ------------------------------------------------------------------
+    # state()
+    # ------------------------------------------------------------------
+
+    @property
+    def state(self) -> IncidentState:
+        return self._state
+
+    def get_state(self) -> Dict[str, Any]:
+        return {
+            "episode_id": self._state.episode_id,
+            "task_name": self._state.task_name,
+            "step_count": self._state.step_count,
+            "time_elapsed_minutes": self._state.time_elapsed_minutes,
+            "done": self._state.done,
+            "cumulative_reward": round(self._state.cumulative_reward, 3),
+            "declared_root_cause": self._state.declared_root_cause,
+        }
+
+    # ------------------------------------------------------------------
+    # Action execution handlers
+    # ------------------------------------------------------------------
+
+    def _execute_action(
+        self, action: IncidentAction
+    ) -> Tuple[Dict[str, Any], str]:
+        """Execute a validated action. Returns (result_dict, message)."""
+        at = action.parsed_type()
+        target = action.target_service
+
+        if at == ActionType.VIEW_ALERTS:
+            alerts = self._infra.get_alerts()
+            return {"alerts": alerts, "count": len(alerts)}, f"Viewing {len(alerts)} active alerts"
+
+        elif at == ActionType.QUERY_LOGS:
+            level_filter = action.parameters.get("level")
+            keyword = action.parameters.get("keyword")
+            limit = action.parameters.get("limit", 15)
+            logs = self._infra.get_logs_for_service(target, level_filter, keyword, limit)
+            return {"logs": logs, "count": len(logs), "service": target}, \
+                   f"Queried {len(logs)} logs from {target}"
+
+        elif at == ActionType.CHECK_METRICS:
+            metrics = self._infra.get_metrics_for_service(target)
+            return {"metrics": metrics, "service": target, "data_points": len(metrics)}, \
+                   f"Retrieved {len(metrics)} metric data points for {target}"
+
+        elif at == ActionType.CHECK_DEPENDENCIES:
+            deps = self._infra.get_dependencies_for_service(target)
+            return {"dependencies": deps, "service": target}, \
+                   f"Retrieved dependency map for {target}"
+
+        elif at == ActionType.CHECK_DEPLOY_HISTORY:
+            deploys = self._infra.get_deploy_history_for_service(target)
+            return {"deploys": deploys, "service": target, "count": len(deploys)}, \
+                   f"Retrieved {len(deploys)} deploys for {target}"
+
+        elif at == ActionType.RUN_HEALTH_CHECK:
+            health = self._infra.run_health_check(target)
+            return {"health_check": health, "service": target}, \
+                   f"Health check for {target}: {health['status']}"
+
+        elif at == ActionType.RESTART_SERVICE:
+            svc = self._infra.get_service(target)
+            msg = svc.restart(self._infra.current_minute) if svc else "Service not found"
+            return {"result": msg, "service": target}, msg
+
+        elif at == ActionType.ROLLBACK_DEPLOY:
+            svc = self._infra.get_service(target)
+            msg = svc.rollback_deploy(self._infra.current_minute) if svc else "Service not found"
+            return {"result": msg, "service": target}, msg
+
+        elif at == ActionType.SCALE_SERVICE:
+            svc = self._infra.get_service(target)
+            new_replicas = action.parameters.get("replicas", 5)
+            msg = svc.scale(new_replicas, self._infra.current_minute) if svc else "Service not found"
+            return {"result": msg, "service": target}, msg
+
+        elif at == ActionType.DECLARE_ROOT_CAUSE:
+            root_cause = action.parameters.get("root_cause", "")
+            self._state.declared_root_cause = root_cause
+            self._root_cause_declared = True
+            return {
+                "declared": root_cause,
+                "message": "Root cause declaration registered. Episode will end after this step.",
+            }, f"Root cause declared: {root_cause}"
+
+        else:
+            return {"error": f"Unhandled action type: {at}"}, "Unknown action"
+
+    # ------------------------------------------------------------------
+    # Reward computation (oracle-shaped — Layer 6)
+    # ------------------------------------------------------------------
+
+    def _compute_reward(self, action: IncidentAction) -> float:
+        """
+        Compute per-step reward using oracle-shaped signal.
+        The training reward has access to hidden state (involved_services,
+        root_cause_service) — this is necessary for learning.
+        The GRADER does NOT use this; it scores trajectory-only.
+        """
+        at = action.parsed_type()
+        target = action.target_service
+        scenario = self._scenario
+        reward = 0.0
+
+        # --- Step penalty (efficiency pressure) ---
+        reward -= 0.02
+
+        # --- Repeat detection ---
+        if self._infra.was_action_taken(action.action_type, target):
+            reward -= 0.05
+            return round(reward, 3)
+
+        # --- Diagnostic actions ---
+        if at in DIAGNOSTIC_ACTIONS:
+            if target and target in scenario.involved_services:
+                reward += 0.15  # Investigating a relevant service
+            elif target and target not in scenario.involved_services:
+                reward += 0.05  # Exploring — not penalized heavily
+            elif at == ActionType.VIEW_ALERTS:
+                reward += 0.15  # Always good to view alerts
+
+        # --- Remediation actions ---
+        elif at in REMEDIATION_ACTIONS:
+            if target == scenario.root_cause_service:
+                reward += 0.30  # Correct remediation target
+            elif target and target in scenario.involved_services:
+                reward += 0.10  # Helpful but not the root cause
+            else:
+                reward -= 0.15  # Remediating healthy/uninvolved service
+
+        # --- Root cause declaration ---
+        elif at == ActionType.DECLARE_ROOT_CAUSE:
+            declared = action.parameters.get("root_cause", "").lower()
+            keywords = scenario.root_cause_keywords
+            if keywords:
+                matched = sum(1 for kw in keywords if kw in declared)
+                ratio = matched / len(keywords)
+                if ratio >= 0.6:
+                    reward += 0.40  # Correct
+                elif ratio >= 0.3:
+                    reward += 0.15  # Partial
+                else:
+                    reward -= 0.20  # Wrong
+            else:
+                reward -= 0.20
+
+        # --- Episode completion bonus/penalty ---
+        if self._root_cause_declared:
+            if self._infra.all_services_healthy():
+                reward += 0.20  # All services restored
+            if self._infra.current_minute > self._infra.time_budget_minutes:
+                reward -= 0.10  # Exceeded time budget
+
+        return round(reward, 3)
+
+    # ------------------------------------------------------------------
+    # Done check
+    # ------------------------------------------------------------------
+
+    def _check_done(self, action: IncidentAction) -> bool:
+        """Episode ends when root cause is declared or max steps reached."""
+        if self._root_cause_declared:
+            return True
+        if self._state.step_count >= self._scenario.max_steps:
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Observation builder
+    # ------------------------------------------------------------------
+
+    def _build_observation(
+        self,
+        action_result: Dict[str, Any],
+        action_success: bool,
+        action_message: str,
+        reward: float,
+    ) -> Dict[str, Any]:
+        """Build the POMDP observation dict (no hidden state exposed)."""
+        statuses = self._infra.get_all_statuses() if self._infra else {}
+        alerts = self._infra.get_alerts() if self._infra else []
+        valid_actions = self._infra.get_valid_actions() if self._infra else []
+
+        return {
+            "incident_summary": self._scenario.incident_summary if self._scenario else "",
+            "severity": self._scenario.severity if self._scenario else "SEV3",
+            "time_elapsed_minutes": self._infra.current_minute if self._infra else 0,
+            "time_budget_minutes": self._infra.time_budget_minutes if self._infra else 30,
+            "action_result": action_result,
+            "action_success": action_success,
+            "action_message": action_message,
+            "service_statuses": statuses,
+            "active_alerts_count": len(alerts),
+            "valid_actions": valid_actions,
+            "available_services": list(SERVICE_NAMES),
+            "current_reward": reward,
+            "cumulative_reward": round(self._cumulative_reward, 3),
+            "steps_taken": self._state.step_count,
+            "max_steps": self._scenario.max_steps if self._scenario else 20,
+            "done": self._done,
+        }
+
+    # ------------------------------------------------------------------
+    # Trajectory recording
+    # ------------------------------------------------------------------
+
+    def _record_step(
+        self,
+        action: IncidentAction,
+        reward: float,
+        observation: Dict[str, Any],
+    ) -> None:
+        """Record step for trajectory-based grading."""
+        record = StepRecord(
+            step_number=self._state.step_count,
+            action=action,
+            reward=reward,
+            observation_summary={
+                "action_message": observation.get("action_message", ""),
+                "active_alerts_count": observation.get("active_alerts_count", 0),
+            },
+            service_statuses_after=dict(observation.get("service_statuses", {})),
+            timestamp_minutes=self._infra.current_minute if self._infra else 0,
+        )
+        self._trajectory.append(record)
+
+    # ------------------------------------------------------------------
+    # Trajectory access (for external grading)
+    # ------------------------------------------------------------------
+
+    def get_trajectory(self) -> List[StepRecord]:
+        return list(self._trajectory)

simulation/__init__.py

@@ -0,0 +1 @@
+# Simulation engine package

simulation/alerts.py

@@ -0,0 +1,145 @@
+"""
+Alert firing engine.
+
+Alerts fire based on metric thresholds — the agent sees what fired
+but must investigate to find why.  Alert correlation (multiple alerts
+from a cascading failure) is represented by shared source timestamps.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Dict, List
+
+from .service import ServiceState
+
+
+# ------------------------------------------------------------------
+# Threshold definitions
+# ------------------------------------------------------------------
+
+_ALERT_RULES = [
+    {
+        "name": "HighErrorRate",
+        "field": "error_rate_percent",
+        "threshold": 10.0,
+        "severity": "critical",
+        "description": "{service}: error rate {value:.1f}% exceeds threshold 10%",
+    },
+    {
+        "name": "HighMemoryUsage",
+        "field": "memory_percent",
+        "threshold": 80.0,
+        "severity": "critical",
+        "description": "{service}: memory usage {value:.0f}% exceeds threshold 80%",
+    },
+    {
+        "name": "HighLatencyP99",
+        "field": "latency_p99_ms",
+        "threshold": 1000.0,
+        "severity": "warning",
+        "description": "{service}: p99 latency {value:.0f}ms exceeds threshold 1000ms",
+    },
+    {
+        "name": "HighLatencyP95",
+        "field": "latency_p95_ms",
+        "threshold": 500.0,
+        "severity": "warning",
+        "description": "{service}: p95 latency {value:.0f}ms exceeds threshold 500ms",
+    },
+    {
+        "name": "HighCPU",
+        "field": "cpu_percent",
+        "threshold": 80.0,
+        "severity": "warning",
+        "description": "{service}: CPU usage {value:.0f}% exceeds threshold 80%",
+    },
+    {
+        "name": "ServiceDown",
+        "field": "status",
+        "threshold": "down",
+        "severity": "critical",
+        "description": "{service}: service is DOWN — health check failing",
+    },
+    {
+        "name": "ServiceDegraded",
+        "field": "status",
+        "threshold": "degraded",
+        "severity": "warning",
+        "description": "{service}: service is DEGRADED — partial failures detected",
+    },
+    {
+        "name": "LowRequestRate",
+        "field": "requests_per_sec",
+        "threshold": 100.0,
+        "severity": "warning",
+        "description": "{service}: request rate {value:.0f} rps dropped below threshold 100 rps",
+        "below": True,
+    },
+]
+
+
+def evaluate_alerts(
+    services: Dict[str, ServiceState],
+    current_minute: int,
+) -> List[Dict[str, Any]]:
+    """
+    Evaluate all alert rules against current service states.
+    Returns list of firing alert dicts.
+    """
+    alerts = []
+    alert_counter = 0
+
+    for svc_name, svc in services.items():
+        for rule in _ALERT_RULES:
+            field = rule["field"]
+            threshold = rule["threshold"]
+
+            # Status-based alerts
+            if field == "status":
+                if svc.status == threshold:
+                    alert_counter += 1
+                    alerts.append({
+                        "alert_id": f"alert-{alert_counter:03d}",
+                        "severity": rule["severity"],
+                        "source_service": svc_name,
+                        "description": rule["description"].format(
+                            service=svc_name, value=0),
+                        "firing_since": f"2025-01-15T14:{max(0, current_minute - svc.ticks_in_down):02d}:00Z"
+                            if threshold == "down"
+                            else f"2025-01-15T14:{max(0, current_minute - svc.ticks_in_degraded):02d}:00Z",
+                        "rule_name": rule["name"],
+                    })
+                continue
+
+            # Numeric threshold alerts
+            value = getattr(svc, field, 0)
+            is_below = rule.get("below", False)
+            triggered = value < threshold if is_below else value > threshold
+
+            if triggered:
+                alert_counter += 1
+                ticks_firing = max(1, len([
+                    h for h in svc.metric_history[-10:]
+                    if (h.get(field.replace("_percent", "").replace("_ms", ""),
+                              h.get(field, 0))
+                        < threshold if is_below
+                        else h.get(field.replace("_percent", "").replace("_ms", ""),
+                                   h.get(field, 0))
+                        > threshold)
+                ]))
+                alerts.append({
+                    "alert_id": f"alert-{alert_counter:03d}",
+                    "severity": rule["severity"],
+                    "source_service": svc_name,
+                    "description": rule["description"].format(
+                        service=svc_name, value=value),
+                    "firing_since": f"2025-01-15T14:{max(0, current_minute - ticks_firing):02d}:00Z",
+                    "rule_name": rule["name"],
+                })
+
+    # Sort by severity: critical first
+    severity_order = {"critical": 0, "warning": 1, "info": 2}
+    alerts.sort(key=lambda a: severity_order.get(a["severity"], 9))
+
+    return alerts

simulation/infrastructure.py

@@ -0,0 +1,297 @@
+"""
+Infrastructure state machine.
+
+Manages the full service topology, cascade propagation, and the
+validate → mutate → tick execution ordering.
+
+This is the central coordinator that scenarios inject faults into
+and the environment executes actions against.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from .service import Deploy, ServiceState
+from .alerts import evaluate_alerts
+from .logs import (
+    generate_noise_logs,
+    generate_red_herring_logs,
+)
+
+
+# ------------------------------------------------------------------
+# Service topology — the dependency graph
+# ------------------------------------------------------------------
+
+SERVICE_NAMES = [
+    "api_gateway", "auth", "orders", "payment",
+    "cache", "database", "queue",
+]
+
+# depends_on: service → list of services it calls
+DEPENDENCY_GRAPH: Dict[str, List[str]] = {
+    "api_gateway": ["auth", "orders", "cache"],
+    "auth":        ["database"],
+    "orders":      ["database", "payment", "auth"],
+    "payment":     ["queue", "database"],
+    "cache":       [],
+    "database":    [],
+    "queue":       [],
+}
+
+
+def _depended_by_graph() -> Dict[str, List[str]]:
+    """Invert the dependency graph: service → who depends on it."""
+    inv: Dict[str, List[str]] = {name: [] for name in SERVICE_NAMES}
+    for service, deps in DEPENDENCY_GRAPH.items():
+        for dep in deps:
+            inv[dep].append(service)
+    return inv
+
+
+DEPENDED_BY = _depended_by_graph()
+
+
+class Infrastructure:
+    """
+    Virtual infrastructure state machine.
+
+    Owns all services, handles cascade propagation, tracks simulation
+    time, and enforces action validation.
+    """
+
+    def __init__(self) -> None:
+        self.services: Dict[str, ServiceState] = {}
+        self.current_minute: int = 0
+        self.time_budget_minutes: int = 30
+        self._actions_taken: List[Tuple[str, Optional[str]]] = []  # (action_type, target)
+        self._all_logs: List[Dict[str, Any]] = []
+        self._setup_services()
+
+    def _setup_services(self) -> None:
+        """Create all seven services with their dependency graphs."""
+        for name in SERVICE_NAMES:
+            svc = ServiceState(
+                name=name,
+                dependencies=list(DEPENDENCY_GRAPH.get(name, [])),
+            )
+            # Give each service a "good" deploy history baseline
+            svc.deploy_history = [
+                Deploy(
+                    version=f"v1.{random.randint(0, 9)}.{random.randint(0, 9)}",
+                    timestamp_minutes=-120,
+                    author=random.choice(["alice", "bob", "charlie", "deploy-bot"]),
+                    commit_hash=f"{random.randint(0, 0xFFFFFF):06x}",
+                    description="Routine release — bug fixes and performance improvements",
+                ),
+            ]
+            # Populate 30 minutes of healthy metric history
+            from .metrics import generate_healthy_history
+            svc.metric_history = generate_healthy_history(30, start_minute=0)
+            svc._reset_metrics_healthy()
+            self.services[name] = svc
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_service(self, name: str) -> Optional[ServiceState]:
+        return self.services.get(name)
+
+    def get_all_statuses(self) -> Dict[str, str]:
+        return {name: svc.status for name, svc in self.services.items()}
+
+    def get_alerts(self) -> List[Dict[str, Any]]:
+        return evaluate_alerts(self.services, self.current_minute)
+
+    def record_action(self, action_type: str, target: Optional[str]) -> None:
+        self._actions_taken.append((action_type, target))
+
+    def was_action_taken(self, action_type: str, target: Optional[str] = None) -> bool:
+        """Check if this exact action was already taken (for repeat detection)."""
+        return (action_type, target) in self._actions_taken
+
+    def action_count(self) -> int:
+        return len(self._actions_taken)
+
+    # ------------------------------------------------------------------
+    # Tick — advances simulation by one minute (called after every step)
+    # ------------------------------------------------------------------
+
+    def tick(self) -> None:
+        """
+        Advance the simulation by one minute.
+        Order: propagate cascades → tick all services → generate noise logs.
+        """
+        self.current_minute += 1
+        self._propagate_cascades()
+
+        for name, svc in self.services.items():
+            new_logs = svc.tick(self.current_minute)
+            self._all_logs.extend(new_logs)
+
+            # Mix in noise and red herrings
+            if random.random() < 0.4:
+                noise = generate_noise_logs(name, self.current_minute, count=1)
+                svc.logs.extend(noise)
+                self._all_logs.extend(noise)
+            if random.random() < 0.15:
+                herrings = generate_red_herring_logs(name, self.current_minute, count=1)
+                svc.logs.extend(herrings)
+                self._all_logs.extend(herrings)
+
+    # ------------------------------------------------------------------
+    # Cascade propagation
+    # ------------------------------------------------------------------
+
+    def _propagate_cascades(self) -> None:
+        """
+        If a service is DOWN or DEGRADED, its downstream dependents
+        should accumulate dependency_degraded faults.
+        If a service recovers, clear the cascaded faults.
+        """
+        for name, svc in self.services.items():
+            dependents = DEPENDED_BY.get(name, [])
+            if svc.status in ("down", "degraded") and svc.active_faults:
+                # Cascade to dependents
+                for dep_name in dependents:
+                    dep_svc = self.services[dep_name]
+                    if not dep_svc.has_fault("dependency_degraded"):
+                        dep_svc.inject_fault("dependency_degraded", upstream=name)
+            elif svc.status == "healthy" and not svc.active_faults:
+                # Service recovered — clear cascade on dependents
+                for dep_name in dependents:
+                    dep_svc = self.services[dep_name]
+                    params = dep_svc.fault_params.get("dependency_degraded", {})
+                    if params.get("upstream") == name:
+                        dep_svc.recover_from_dependency(self.current_minute)
+
+    # ------------------------------------------------------------------
+    # Validation — Layer 5: validate BEFORE mutating
+    # ------------------------------------------------------------------
+
+    def validate_action(
+        self,
+        action_type: str,
+        target_service: Optional[str],
+    ) -> Tuple[bool, str]:
+        """
+        Validate that an action is legal in the current state.
+        Returns (is_valid, error_message).
+        """
+        from ..models import ActionType, TARGETED_ACTIONS
+
+        try:
+            at = ActionType(action_type)
+        except ValueError:
+            return False, f"Unknown action type: {action_type}"
+
+        if at in TARGETED_ACTIONS:
+            if not target_service:
+                return False, f"Action {action_type} requires a target_service"
+            if target_service not in self.services:
+                return False, f"Unknown service: {target_service}"
+
+        # Specific validations (action masking)
+        if at == ActionType.ROLLBACK_DEPLOY:
+            svc = self.services.get(target_service, None)
+            if svc and len(svc.deploy_history) < 2:
+                return False, f"No previous deploy to rollback to for {target_service}"
+
+        if at == ActionType.SCALE_SERVICE:
+            svc = self.services.get(target_service, None)
+            if svc and svc.status == "down":
+                return False, f"Cannot scale {target_service} — service is DOWN"
+
+        return True, ""
+
+    def get_valid_actions(self) -> List[str]:
+        """
+        Return list of valid (action_type, target) descriptions.
+        Used to populate valid_actions[] in the observation.
+        """
+        from ..models import ActionType, TARGETED_ACTIONS
+        valid = []
+        for at in ActionType:
+            if at in TARGETED_ACTIONS:
+                for svc_name in self.services:
+                    is_valid, _ = self.validate_action(at.value, svc_name)
+                    if is_valid:
+                        valid.append(f"{at.value}:{svc_name}")
+            else:
+                valid.append(at.value)
+        return valid
+
+    # ------------------------------------------------------------------
+    # Service queries (observation builders)
+    # ------------------------------------------------------------------
+
+    def get_logs_for_service(
+        self,
+        service_name: str,
+        level_filter: Optional[str] = None,
+        keyword: Optional[str] = None,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        """Query logs for a service with optional filtering."""
+        svc = self.services.get(service_name)
+        if not svc:
+            return []
+
+        logs = list(svc.logs)
+        if level_filter:
+            logs = [l for l in logs if l.get("level", "").upper() == level_filter.upper()]
+        if keyword:
+            kw = keyword.lower()
+            logs = [l for l in logs if kw in l.get("message", "").lower()]
+        return logs[-limit:]
+
+    def get_metrics_for_service(self, service_name: str) -> List[Dict[str, float]]:
+        svc = self.services.get(service_name)
+        return list(svc.metric_history) if svc else []
+
+    def get_dependencies_for_service(self, service_name: str) -> Dict[str, List[str]]:
+        return {
+            "depends_on": list(DEPENDENCY_GRAPH.get(service_name, [])),
+            "depended_by": list(DEPENDED_BY.get(service_name, [])),
+        }
+
+    def get_deploy_history_for_service(self, service_name: str) -> List[Dict[str, Any]]:
+        svc = self.services.get(service_name)
+        if not svc:
+            return []
+        return [
+            {
+                "version": d.version,
+                "timestamp": f"2025-01-15T{14 + d.timestamp_minutes // 60:02d}:"
+                             f"{d.timestamp_minutes % 60:02d}:00Z"
+                             if d.timestamp_minutes >= 0
+                             else f"2025-01-15T{12 + (d.timestamp_minutes + 120) // 60:02d}:"
+                                  f"{(d.timestamp_minutes + 120) % 60:02d}:00Z",
+                "author": d.author,
+                "commit_hash": d.commit_hash,
+                "description": d.description,
+            }
+            for d in svc.deploy_history
+        ]
+
+    def run_health_check(self, service_name: str) -> Dict[str, Any]:
+        svc = self.services.get(service_name)
+        if not svc:
+            return {"status": "unknown", "response_time_ms": 0}
+        response_time = {
+            "healthy": random.randint(5, 50),
+            "degraded": random.randint(200, 2000),
+            "down": 30000,  # timeout
+        }.get(svc.status, 0)
+        return {
+            "status": svc.status,
+            "response_time_ms": response_time,
+            "replicas": svc.replica_count,
+            "active_faults_count": len(svc.active_faults),  # agent can see SOMETHING is wrong
+        }
+
+    def all_services_healthy(self) -> bool:
+        return all(svc.status == "healthy" for svc in self.services.values())

simulation/logs.py

@@ -0,0 +1,198 @@
+"""
+Log stream generator.
+
+Produces realistic structured log entries — both signal and noise.
+Red herring logs are mixed in so the agent must filter real evidence
+from routine chatter.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Dict, List, Optional
+
+
+# ------------------------------------------------------------------
+# Noise logs — routine operational chatter
+# ------------------------------------------------------------------
+
+_NOISE_TEMPLATES = [
+    ("INFO", "Processed {n} requests in last 60 seconds"),
+    ("INFO", "Health check passed — all dependencies reachable"),
+    ("INFO", "Connection pool stats: active={a}, idle={i}, max={m}"),
+    ("DEBUG", "Cache hit ratio: {r:.1%} — {h} hits, {m} misses"),
+    ("INFO", "Scheduled job 'metrics_export' completed in {d}ms"),
+    ("DEBUG", "TLS handshake completed with upstream in {d}ms"),
+    ("INFO", "Config reload: no changes detected"),
+    ("WARN", "Slow query detected: SELECT * FROM sessions took {d}ms"),
+    ("INFO", "Garbage collection: freed {n}MB in {d}ms"),
+    ("DEBUG", "Rate limiter: {n} requests allowed, 0 throttled"),
+]
+
+
+def generate_noise_logs(
+    service_name: str,
+    current_minute: int,
+    count: int = 3,
+) -> List[Dict[str, Any]]:
+    """Generate routine noise logs for a service."""
+    logs = []
+    for _ in range(count):
+        template_level, template_msg = random.choice(_NOISE_TEMPLATES)
+        msg = template_msg.format(
+            n=random.randint(100, 5000),
+            a=random.randint(5, 20),
+            i=random.randint(0, 10),
+            m=random.randint(20, 50),
+            r=random.uniform(0.85, 0.99),
+            h=random.randint(1000, 9000),
+            d=random.randint(1, 500),
+        )
+        logs.append({
+            "timestamp": f"2025-01-15T14:{current_minute:02d}:{random.randint(0,59):02d}Z",
+            "level": template_level,
+            "service": service_name,
+            "message": msg,
+            "trace_id": None,
+        })
+    return logs
+
+
+# ------------------------------------------------------------------
+# Scenario-specific log generators (signal)
+# ------------------------------------------------------------------
+
+def generate_memory_leak_logs(
+    service_name: str,
+    current_minute: int,
+    memory_percent: float,
+) -> List[Dict[str, Any]]:
+    """Logs that indicate a memory leak is in progress."""
+    logs = []
+    trace = f"trace-{random.randint(100000, 999999)}"
+
+    if memory_percent > 90:
+        logs.append(_log(current_minute, "FATAL", service_name,
+            f"OutOfMemoryError: Java heap space — requested 256MB, "
+            f"available 12MB", trace))
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Container {service_name}-{random.randint(0,2)} killed by OOM killer "
+            f"(exit code 137)", trace))
+    elif memory_percent > 80:
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Memory allocation failed: unable to allocate {random.randint(64, 256)}MB "
+            f"for request processing", trace))
+        logs.append(_log(current_minute, "WARN", service_name,
+            f"GC overhead limit exceeded: spent {random.randint(80, 97)}% of time in GC"))
+    elif memory_percent > 70:
+        logs.append(_log(current_minute, "WARN", service_name,
+            f"Heap usage warning: {memory_percent:.0f}% — approaching limit. "
+            f"Consider increasing -Xmx or investigating leaks"))
+
+    return logs
+
+
+def generate_auth_failure_logs(
+    service_name: str,
+    current_minute: int,
+    is_auth_service: bool = False,
+) -> List[Dict[str, Any]]:
+    """Logs for auth-related failures (used in cascading failure scenario)."""
+    logs = []
+    trace = f"trace-{random.randint(100000, 999999)}"
+
+    if is_auth_service:
+        logs.append(_log(current_minute, "ERROR", service_name,
+            "NullPointerException: configuration key 'auth.jwt.secret' is null "
+            "— cannot validate tokens", trace))
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Authentication failed for {random.randint(50, 200)} requests in "
+            f"last 60s — returning HTTP 500"))
+    else:
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Call to auth-service failed: HTTP 500 Internal Server Error "
+            f"— retrying ({random.randint(1,3)}/3)", trace))
+        logs.append(_log(current_minute, "WARN", service_name,
+            f"Circuit breaker for auth-service: state=HALF_OPEN, "
+            f"failures={random.randint(5, 20)}, threshold=10"))
+
+    return logs
+
+
+def generate_deadlock_logs(
+    service_name: str,
+    current_minute: int,
+    waiting_on: str,
+) -> List[Dict[str, Any]]:
+    """Logs for distributed deadlock / circular wait."""
+    logs = []
+    trace = f"trace-{random.randint(100000, 999999)}"
+
+    logs.append(_log(current_minute, "WARN", service_name,
+        f"Request {trace} waiting on {waiting_on}: blocked for "
+        f"{random.randint(5000, 25000)}ms — no response", trace))
+
+    if random.random() < 0.4:
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Timeout calling {waiting_on}: deadline exceeded after 30000ms. "
+            f"Retry attempt {random.randint(3, 8)} of 10", trace))
+
+    if random.random() < 0.2:
+        logs.append(_log(current_minute, "ERROR", service_name,
+            f"Thread pool exhausted: all {random.randint(50, 200)} threads blocked "
+            f"waiting on downstream calls"))
+
+    return logs
+
+
+# ------------------------------------------------------------------
+# Red herring logs — plausible but misleading
+# ------------------------------------------------------------------
+
+_RED_HERRING_TEMPLATES = [
+    ("WARN", "DNS resolution for {svc}.internal took {d}ms (threshold: 100ms)"),
+    ("WARN", "TLS certificate for {svc}.internal expires in {n} days"),
+    ("WARN", "Disk usage on /var/log: {n}% — consider log rotation"),
+    ("ERROR", "Failed to export metrics to Prometheus: connection timeout after {d}ms"),
+    ("WARN", "Background job 'cleanup_sessions' took {d}ms (expected <500ms)"),
+    ("ERROR", "Redis SLOWLOG: KEYS pattern='session:*' took {d}ms"),
+]
+
+
+def generate_red_herring_logs(
+    service_name: str,
+    current_minute: int,
+    count: int = 1,
+) -> List[Dict[str, Any]]:
+    """Generate plausible but misleading log entries."""
+    logs = []
+    services = ["api_gateway", "auth", "orders", "payment", "cache", "database", "queue"]
+    for _ in range(count):
+        level, tmpl = random.choice(_RED_HERRING_TEMPLATES)
+        msg = tmpl.format(
+            svc=random.choice(services),
+            d=random.randint(100, 3000),
+            n=random.randint(3, 85),
+        )
+        logs.append(_log(current_minute, level, service_name, msg))
+    return logs
+
+
+# ------------------------------------------------------------------
+# Helper
+# ------------------------------------------------------------------
+
+def _log(
+    minute: int,
+    level: str,
+    service: str,
+    message: str,
+    trace_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    return {
+        "timestamp": f"2025-01-15T14:{minute:02d}:{random.randint(0,59):02d}Z",
+        "level": level,
+        "service": service,
+        "message": message,
+        "trace_id": trace_id,
+    }

simulation/metrics.py

@@ -0,0 +1,147 @@
+"""
+Metric time-series generator.
+
+Produces plausible metric history for services — both the healthy baseline
+and the anomaly window. Used to populate metric_history on reset so the
+agent sees a 30-minute lookback, not just the current point.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, List
+
+
+def generate_healthy_history(
+    minutes: int = 30,
+    start_minute: int = 0,
+) -> List[Dict[str, float]]:
+    """Generate 'minutes' worth of normal baseline metrics."""
+    history = []
+    for m in range(start_minute, start_minute + minutes):
+        noise = lambda: random.gauss(0, 1)
+        history.append({
+            "minute": m,
+            "cpu": round(max(5, min(40, 15 + noise() * 3)), 1),
+            "memory": round(max(20, min(55, 35 + noise() * 3)), 1),
+            "error_rate": round(max(0, min(2, 0.1 + abs(noise()) * 0.1)), 2),
+            "latency_p50": round(max(5, 12 + noise() * 2), 1),
+            "latency_p95": round(max(20, 45 + noise() * 5), 1),
+            "latency_p99": round(max(50, 120 + noise() * 10), 1),
+            "rps": round(max(200, 500 + noise() * 30), 1),
+        })
+    return history
+
+
+def generate_memory_leak_history(
+    minutes: int = 30,
+    start_minute: int = 0,
+    leak_start_offset: int = 10,
+    rate: float = 1.5,
+) -> List[Dict[str, float]]:
+    """
+    Generate metric history with a memory leak starting partway through.
+    First 'leak_start_offset' minutes are normal, then memory climbs.
+    """
+    history = []
+    mem = 35.0
+    for m in range(start_minute, start_minute + minutes):
+        noise = lambda: random.gauss(0, 1)
+        elapsed = m - start_minute
+        if elapsed >= leak_start_offset:
+            mem = min(99.0, mem + rate + noise() * 0.3)
+            cpu = min(95, 15 + (elapsed - leak_start_offset) * 0.3 + noise() * 2)
+            error_rate = max(0, min(100, (mem - 75) * 2 + noise() * 2)) if mem > 75 else 0.1
+            lat_p95 = max(45, 45 + (mem - 70) * 8 + noise() * 10) if mem > 70 else 45 + noise() * 5
+            lat_p99 = max(120, lat_p95 * 2.5 + noise() * 20)
+        else:
+            cpu = max(5, min(40, 15 + noise() * 3))
+            mem = max(20, min(55, 35 + noise() * 3))
+            error_rate = max(0, 0.1 + abs(noise()) * 0.1)
+            lat_p95 = max(20, 45 + noise() * 5)
+            lat_p99 = max(50, 120 + noise() * 10)
+
+        history.append({
+            "minute": m,
+            "cpu": round(cpu, 1),
+            "memory": round(mem, 1),
+            "error_rate": round(error_rate, 2),
+            "latency_p50": round(max(5, 12 + noise() * 2), 1),
+            "latency_p95": round(lat_p95, 1),
+            "latency_p99": round(lat_p99, 1),
+            "rps": round(max(100, 500 - max(0, mem - 80) * 15 + noise() * 20), 1),
+        })
+    return history
+
+
+def generate_error_spike_history(
+    minutes: int = 30,
+    start_minute: int = 0,
+    spike_start_offset: int = 5,
+    error_rate_target: float = 60.0,
+) -> List[Dict[str, float]]:
+    """Metric history where error rate jumps suddenly (e.g. bad config push)."""
+    history = []
+    for m in range(start_minute, start_minute + minutes):
+        noise = lambda: random.gauss(0, 1)
+        elapsed = m - start_minute
+        if elapsed >= spike_start_offset:
+            error_rate = min(100, error_rate_target + noise() * 5)
+            lat_p95 = max(100, 500 + noise() * 50)
+            lat_p99 = max(200, 1500 + noise() * 100)
+            cpu = max(5, min(80, 40 + noise() * 5))
+        else:
+            error_rate = max(0, 0.1 + abs(noise()) * 0.1)
+            lat_p95 = max(20, 45 + noise() * 5)
+            lat_p99 = max(50, 120 + noise() * 10)
+            cpu = max(5, min(40, 15 + noise() * 3))
+
+        history.append({
+            "minute": m,
+            "cpu": round(cpu, 1),
+            "memory": round(max(20, min(55, 35 + noise() * 3)), 1),
+            "error_rate": round(error_rate, 2),
+            "latency_p50": round(max(5, 12 + noise() * 2), 1),
+            "latency_p95": round(lat_p95, 1),
+            "latency_p99": round(lat_p99, 1),
+            "rps": round(max(100, 500 - error_rate * 3 + noise() * 20), 1),
+        })
+    return history
+
+
+def generate_high_latency_history(
+    minutes: int = 30,
+    start_minute: int = 0,
+    latency_start_offset: int = 8,
+    target_p99: float = 8000,
+) -> List[Dict[str, float]]:
+    """Metric history with gradually increasing latency (deadlock/contention)."""
+    history = []
+    for m in range(start_minute, start_minute + minutes):
+        noise = lambda: random.gauss(0, 1)
+        elapsed = m - start_minute
+        if elapsed >= latency_start_offset:
+            progress = min(1.0, (elapsed - latency_start_offset) / 15)
+            lat_p50 = max(12, 12 + progress * 400 + noise() * 20)
+            lat_p95 = max(45, 45 + progress * target_p99 * 0.6 + noise() * 80)
+            lat_p99 = max(120, 120 + progress * target_p99 + noise() * 200)
+            error_rate = max(0, progress * 15 + noise() * 2)
+            rps = max(20, 500 * (1 - progress * 0.7) + noise() * 15)
+        else:
+            lat_p50 = max(5, 12 + noise() * 2)
+            lat_p95 = max(20, 45 + noise() * 5)
+            lat_p99 = max(50, 120 + noise() * 10)
+            error_rate = max(0, 0.1 + abs(noise()) * 0.1)
+            rps = max(200, 500 + noise() * 30)
+
+        history.append({
+            "minute": m,
+            "cpu": round(max(5, min(60, 15 + noise() * 3)), 1),
+            "memory": round(max(20, min(55, 35 + noise() * 3)), 1),
+            "error_rate": round(error_rate, 2),
+            "latency_p50": round(lat_p50, 1),
+            "latency_p95": round(lat_p95, 1),
+            "latency_p99": round(lat_p99, 1),
+            "rps": round(rps, 1),
+        })
+    return history

simulation/service.py

@@ -0,0 +1,335 @@
+"""
+Individual service simulator.
+
+Each service is a stateful entity with health, metrics, logs, deploy history,
+and fault injection points.  When faults are injected, metrics respond
+reactively — memory climbs, error rates spike, latency degrades — and the
+service produces appropriate log entries automatically.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Deploy:
+    """A single deploy record."""
+    version: str
+    timestamp_minutes: int      # simulation minutes since epoch
+    author: str
+    commit_hash: str
+    description: str
+    is_bad: bool = False        # hidden — grader never sees this directly
+
+
+@dataclass
+class ServiceState:
+    """
+    Full mutable state for one service.
+
+    The agent NEVER sees this directly. It can only observe symptoms
+    through the five observation modalities (alerts, metrics, logs, deps, deploys).
+    """
+    name: str
+    status: str = "healthy"                         # healthy | degraded | down
+    dependencies: List[str] = field(default_factory=list)
+
+    # --- Metrics (reactive) ---
+    cpu_percent: float = 15.0
+    memory_percent: float = 35.0
+    error_rate_percent: float = 0.1
+    latency_p50_ms: float = 12.0
+    latency_p95_ms: float = 45.0
+    latency_p99_ms: float = 120.0
+    requests_per_sec: float = 500.0
+
+    # --- Metric history (last 30 data points = 30 minutes) ---
+    metric_history: List[Dict[str, float]] = field(default_factory=list)
+
+    # --- Logs (circular buffer, last 50) ---
+    logs: List[Dict[str, Any]] = field(default_factory=list)
+
+    # --- Deploy history ---
+    deploy_history: List[Deploy] = field(default_factory=list)
+
+    # --- Fault state (hidden — drives reactive behavior) ---
+    active_faults: List[str] = field(default_factory=list)
+    fault_params: Dict[str, Any] = field(default_factory=dict)
+
+    # --- Operational ---
+    replica_count: int = 3
+    restarts_since_fault: int = 0
+    ticks_in_degraded: int = 0
+    ticks_in_down: int = 0
+    was_rolled_back: bool = False
+
+    # ---------------------------------------------------------------
+    # Fault injection — called by scenarios at setup time
+    # ---------------------------------------------------------------
+
+    def inject_fault(self, fault_type: str, **params: Any) -> None:
+        """Inject a named fault. Metrics will react on subsequent ticks."""
+        self.active_faults.append(fault_type)
+        self.fault_params[fault_type] = params
+
+    def clear_fault(self, fault_type: str) -> None:
+        """Remove a fault (e.g. after rollback fixes the root cause)."""
+        if fault_type in self.active_faults:
+            self.active_faults.remove(fault_type)
+            self.fault_params.pop(fault_type, None)
+
+    def clear_all_faults(self) -> None:
+        self.active_faults.clear()
+        self.fault_params.clear()
+
+    def has_fault(self, fault_type: str) -> bool:
+        return fault_type in self.active_faults
+
+    # ---------------------------------------------------------------
+    # Tick — advance one simulation minute.  Metrics react to faults.
+    # ---------------------------------------------------------------
+
+    def tick(self, current_minute: int) -> List[Dict[str, Any]]:
+        """
+        Advance the service by one simulation minute.
+        Returns any new log entries generated this tick.
+        """
+        new_logs: List[Dict[str, Any]] = []
+        noise = lambda: random.gauss(0, 1)
+
+        # --- Memory leak: memory climbs steadily ---
+        if "memory_leak" in self.active_faults:
+            rate = self.fault_params.get("memory_leak", {}).get("rate", 1.5)
+            self.memory_percent = min(99.0, self.memory_percent + rate + noise() * 0.3)
+            self.cpu_percent = min(95.0, self.cpu_percent + 0.3 + noise() * 0.2)
+            if self.memory_percent > 90:
+                self.status = "down"
+                self.error_rate_percent = min(100.0, 85.0 + noise() * 5)
+                new_logs.append(self._log(current_minute, "FATAL",
+                    f"OutOfMemoryError: Java heap space — service {self.name} killed by OOM killer"))
+                new_logs.append(self._log(current_minute, "ERROR",
+                    f"Container {self.name}-0 exited with code 137 (OOMKilled)"))
+            elif self.memory_percent > 75:
+                self.status = "degraded"
+                self.error_rate_percent = min(50.0, 15.0 + (self.memory_percent - 75) * 1.5 + noise() * 2)
+                self.latency_p95_ms = max(self.latency_p95_ms, 200 + noise() * 20)
+                self.latency_p99_ms = max(self.latency_p99_ms, 500 + noise() * 30)
+                new_logs.append(self._log(current_minute, "WARN",
+                    f"GC pressure: heap usage at {self.memory_percent:.0f}%, "
+                    f"GC pause {random.randint(200, 800)}ms"))
+
+        # --- High error rate (e.g. bad config) ---
+        if "high_error_rate" in self.active_faults:
+            target_rate = self.fault_params.get("high_error_rate", {}).get("rate", 60.0)
+            self.error_rate_percent = min(100.0, target_rate + noise() * 5)
+            if self.error_rate_percent > 50:
+                self.status = "down"
+                new_logs.append(self._log(current_minute, "ERROR",
+                    f"Health check failed: {self.name} returned HTTP 500"))
+            elif self.error_rate_percent > 20:
+                self.status = "degraded"
+            new_logs.append(self._log(current_minute, "ERROR",
+                f"Internal Server Error: configuration key 'auth.token.secret' is null"))
+
+        # --- High latency (e.g. deadlock / contention) ---
+        if "high_latency" in self.active_faults:
+            target_p99 = self.fault_params.get("high_latency", {}).get("p99", 5000)
+            self.latency_p50_ms = min(2000, 300 + noise() * 30)
+            self.latency_p95_ms = min(8000, target_p99 * 0.7 + noise() * 100)
+            self.latency_p99_ms = min(15000, target_p99 + noise() * 200)
+            self.error_rate_percent = min(40.0, 10.0 + noise() * 3)
+            self.status = "degraded"
+            new_logs.append(self._log(current_minute, "WARN",
+                f"Request timeout: upstream call to dependency exceeded 5000ms"))
+
+        # --- Dependency degradation (cascaded from upstream) ---
+        if "dependency_degraded" in self.active_faults:
+            upstream = self.fault_params.get("dependency_degraded", {}).get("upstream", "unknown")
+            self.error_rate_percent = min(80.0, 25.0 + noise() * 8)
+            self.latency_p95_ms = max(self.latency_p95_ms, 1500 + noise() * 100)
+            self.latency_p99_ms = max(self.latency_p99_ms, 3000 + noise() * 200)
+            if self.error_rate_percent > 50:
+                self.status = "down"
+            else:
+                self.status = "degraded"
+            new_logs.append(self._log(current_minute, "ERROR",
+                f"Connection refused: {upstream}:8080 — upstream service unavailable"))
+
+        # --- Circular wait / deadlock ---
+        if "circular_wait" in self.active_faults:
+            peers = self.fault_params.get("circular_wait", {}).get("peers", [])
+            self.latency_p50_ms = min(3000, 500 + noise() * 50)
+            self.latency_p95_ms = min(10000, 4000 + noise() * 200)
+            self.latency_p99_ms = min(30000, 8000 + noise() * 500)
+            self.error_rate_percent = min(30.0, 12.0 + noise() * 3)
+            self.requests_per_sec = max(10, self.requests_per_sec * 0.85)
+            self.status = "degraded"
+            peer = random.choice(peers) if peers else "unknown"
+            new_logs.append(self._log(current_minute, "WARN",
+                f"Timeout waiting for response from {peer}: "
+                f"request {self._trace_id()} blocked for {random.randint(5000, 15000)}ms"))
+            if random.random() < 0.3:
+                new_logs.append(self._log(current_minute, "ERROR",
+                    f"Retry exhausted for {peer}: CircuitBreaker OPEN after 5 consecutive failures"))
+
+        # --- Healthy service noise ---
+        if not self.active_faults:
+            self._tick_healthy(current_minute)
+        else:
+            self.ticks_in_degraded += 1 if self.status == "degraded" else 0
+            self.ticks_in_down += 1 if self.status == "down" else 0
+
+        # Record metric snapshot
+        self.metric_history.append({
+            "minute": current_minute,
+            "cpu": round(self.cpu_percent, 1),
+            "memory": round(self.memory_percent, 1),
+            "error_rate": round(self.error_rate_percent, 2),
+            "latency_p50": round(self.latency_p50_ms, 1),
+            "latency_p95": round(self.latency_p95_ms, 1),
+            "latency_p99": round(self.latency_p99_ms, 1),
+            "rps": round(self.requests_per_sec, 1),
+        })
+        # Keep last 30 data points
+        if len(self.metric_history) > 30:
+            self.metric_history = self.metric_history[-30:]
+
+        # Keep last 50 logs
+        self.logs.extend(new_logs)
+        if len(self.logs) > 50:
+            self.logs = self.logs[-50:]
+
+        return new_logs
+
+    # ---------------------------------------------------------------
+    # Remediation actions
+    # ---------------------------------------------------------------
+
+    def restart(self, current_minute: int) -> str:
+        """
+        Restart the service.  Temporarily fixes symptoms but NOT root cause
+        unless the fault has been cleared first (e.g. via rollback).
+        """
+        self.restarts_since_fault += 1
+
+        if not self.active_faults:
+            # Service is healthy — restart is unnecessary
+            self.status = "healthy"
+            self.logs.append(self._log(current_minute, "INFO",
+                f"Service {self.name} restarted (was already healthy)"))
+            return f"{self.name} restarted (was already healthy)"
+
+        # Reset metrics temporarily — faults will re-corrupt on next tick
+        self.memory_percent = 35.0 + random.gauss(0, 3)
+        self.cpu_percent = 15.0 + random.gauss(0, 2)
+        self.error_rate_percent = max(0.1, self.error_rate_percent * 0.3)
+        self.latency_p50_ms = 12.0 + random.gauss(0, 2)
+        self.latency_p95_ms = 45.0 + random.gauss(0, 5)
+        self.latency_p99_ms = 120.0 + random.gauss(0, 10)
+        self.status = "healthy"
+
+        self.logs.append(self._log(current_minute, "INFO",
+            f"Service {self.name} restarted — metrics reset. "
+            f"NOTE: underlying issue may recur."))
+        return f"{self.name} restarted — metrics temporarily reset"
+
+    def rollback_deploy(self, current_minute: int) -> str:
+        """
+        Roll back to the previous deploy.
+        If the active fault was caused by a bad deploy, this FIXES IT.
+        """
+        if len(self.deploy_history) < 2:
+            return f"No previous deploy to rollback to for {self.name}"
+
+        bad_deploy = self.deploy_history[-1]
+        prev_deploy = self.deploy_history[-2]
+
+        self.was_rolled_back = True
+
+        # If the bad deploy is what caused the fault, clear it
+        if bad_deploy.is_bad:
+            self.clear_all_faults()
+            self.status = "healthy"
+            self._reset_metrics_healthy()
+            self.logs.append(self._log(current_minute, "INFO",
+                f"Rolled back {self.name} from {bad_deploy.version} to "
+                f"{prev_deploy.version} — fault cleared"))
+            return (f"Rolled back {self.name} from {bad_deploy.version} to "
+                    f"{prev_deploy.version} — service recovering")
+        else:
+            self.logs.append(self._log(current_minute, "INFO",
+                f"Rolled back {self.name} from {bad_deploy.version} to "
+                f"{prev_deploy.version} — no change in symptoms"))
+            return (f"Rolled back {self.name} to {prev_deploy.version} "
+                    f"— symptoms unchanged (likely not the cause)")
+
+    def scale(self, new_replicas: int, current_minute: int) -> str:
+        """Scale to new replica count. Helps with load but not root cause."""
+        old = self.replica_count
+        self.replica_count = max(1, min(10, new_replicas))
+        if self.replica_count > old and "circular_wait" not in self.active_faults:
+            # Scaling up reduces latency proportionally
+            factor = old / self.replica_count
+            self.latency_p50_ms *= factor
+            self.latency_p95_ms *= factor
+            self.latency_p99_ms *= factor
+            self.requests_per_sec /= factor
+        self.logs.append(self._log(current_minute, "INFO",
+            f"Scaled {self.name} from {old} to {self.replica_count} replicas"))
+        return f"Scaled {self.name}: {old} -> {self.replica_count} replicas"
+
+    # ---------------------------------------------------------------
+    # Recovery after upstream fix
+    # ---------------------------------------------------------------
+
+    def recover_from_dependency(self, current_minute: int) -> None:
+        """Called when an upstream fault clears — this service should heal."""
+        self.clear_fault("dependency_degraded")
+        if not self.active_faults:
+            self.status = "healthy"
+            self._reset_metrics_healthy()
+            self.logs.append(self._log(current_minute, "INFO",
+                f"Service {self.name} recovering — upstream dependency restored"))
+
+    # ---------------------------------------------------------------
+    # Internals
+    # ---------------------------------------------------------------
+
+    def _tick_healthy(self, current_minute: int) -> None:
+        """Normal baseline metric jitter for healthy services."""
+        noise = lambda: random.gauss(0, 1)
+        self.cpu_percent = max(5, min(40, 15 + noise() * 3))
+        self.memory_percent = max(20, min(55, 35 + noise() * 3))
+        self.error_rate_percent = max(0, min(2, 0.1 + abs(noise()) * 0.1))
+        self.latency_p50_ms = max(5, 12 + noise() * 2)
+        self.latency_p95_ms = max(20, 45 + noise() * 5)
+        self.latency_p99_ms = max(50, 120 + noise() * 10)
+        self.requests_per_sec = max(200, 500 + noise() * 30)
+        self.status = "healthy"
+
+    def _reset_metrics_healthy(self) -> None:
+        """Fully reset to healthy baseline."""
+        self.cpu_percent = 15.0 + random.gauss(0, 2)
+        self.memory_percent = 35.0 + random.gauss(0, 3)
+        self.error_rate_percent = 0.1 + abs(random.gauss(0, 0.05))
+        self.latency_p50_ms = 12.0 + random.gauss(0, 1)
+        self.latency_p95_ms = 45.0 + random.gauss(0, 3)
+        self.latency_p99_ms = 120.0 + random.gauss(0, 8)
+        self.requests_per_sec = 500.0 + random.gauss(0, 20)
+        self.status = "healthy"
+
+    def _log(self, minute: int, level: str, message: str) -> Dict[str, Any]:
+        return {
+            "timestamp": f"2025-01-15T14:{minute:02d}:00Z",
+            "level": level,
+            "service": self.name,
+            "message": message,
+            "trace_id": self._trace_id() if level in ("ERROR", "FATAL") else None,
+        }
+
+    @staticmethod
+    def _trace_id() -> str:
+        return f"trace-{random.randint(100000, 999999)}"

tasks.py

@@ -0,0 +1,47 @@
+"""
+Task registry and evaluation graders.
+
+Each task maps to a scenario.  The grader is oracle-independent —
+it takes only List[StepRecord] and returns a float in [0, 1].
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Type
+
+from .models import StepRecord
+from .scenarios.base import BaseScenario
+from .scenarios.easy_memory_leak import MemoryLeakScenario
+from .scenarios.medium_cascading_failure import CascadingFailureScenario
+from .scenarios.hard_distributed_deadlock import DistributedDeadlockScenario
+
+
+# ------------------------------------------------------------------
+# Registry
+# ------------------------------------------------------------------
+
+TASK_REGISTRY: Dict[str, Type[BaseScenario]] = {
+    "memory_leak": MemoryLeakScenario,
+    "cascading_failure": CascadingFailureScenario,
+    "distributed_deadlock": DistributedDeadlockScenario,
+}
+
+TASK_NAMES = list(TASK_REGISTRY.keys())
+
+
+def get_scenario(task_name: str) -> BaseScenario:
+    """Instantiate a scenario by task name."""
+    cls = TASK_REGISTRY.get(task_name)
+    if cls is None:
+        raise ValueError(
+            f"Unknown task: {task_name}. Available: {TASK_NAMES}")
+    return cls()
+
+
+def grade_trajectory(task_name: str, trajectory: List[StepRecord]) -> float:
+    """
+    Grade a trajectory for a given task.
+    This is the evaluation entry point — standalone, no hidden state.
+    """
+    scenario = get_scenario(task_name)
+    return scenario.grade(trajectory)