fix: add missing OpenEnv files + fix HF Spaces logging

- Add client.py, models.py, uv.lock (were gitignored/untracked)
- Fix .gitignore: stop excluding uv.lock (required by OpenEnv)
- Fix server logging: use stderr for HF Spaces container log capture
- Root '/' now redirects to /dashboard for better Spaces preview
- Add boot timestamp and endpoint URLs to startup logs

Author: Jitraj277

.gitignore

@@ -4,7 +4,8 @@ __pycache__/
 *.egg-info/
 .env
 .DS_Store
-*.lock
+# Keep uv.lock tracked (required by OpenEnv)
+package-lock.json
 dist/
 build/
 missionctrl_checkpoints/

README.md

@@ -1,3 +1,13 @@
+---
+title: MissionCtrl
+emoji: 🛡️
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 8000
+pinned: false
+---
+
 # 🛡️ MissionCtrl — AI Oversight Fleet Environment
 
 > *Every LLM agent fleet will hallucinate. MissionCtrl trains the overseer to catch them.*

__init__.py

@@ -4,7 +4,11 @@
 from a fleet of 5 specialist AI sub-agents.
 """
 
+from .models import MissionCtrlAction, MissionCtrlObservation
+from .client import MissionCtrlEnv
+
 __all__ = [
     "MissionCtrlAction",
     "MissionCtrlObservation",
+    "MissionCtrlEnv",
 ]

client.py

@@ -0,0 +1,111 @@
+"""MissionCtrl Environment Client.
+
+Typed EnvClient for the MissionCtrl AI Oversight Fleet Environment.
+Connects to the FastAPI server and provides a structured Python interface
+for reset / step / state interactions.
+
+Example:
+    >>> with MissionCtrlEnv(base_url="http://localhost:8000") as client:
+    ...     result = client.reset()
+    ...     print(result.observation.tasks)
+    ...
+    ...     result = client.step(MissionCtrlAction(action="APPROVE(task_01)"))
+    ...     print(result.observation.time_step, result.reward)
+"""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import MissionCtrlAction, MissionCtrlObservation
+
+
+class MissionCtrlEnv(
+    EnvClient[MissionCtrlAction, MissionCtrlObservation, State]
+):
+    """
+    Client for the MissionCtrl AI Oversight Fleet Environment.
+
+    Maintains a persistent connection to the environment server, enabling
+    efficient multi-step interactions with lower latency. Each client
+    instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> with MissionCtrlEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     obs = result.observation
+        ...     for task in obs.tasks:
+        ...         print(task["task_id"], task["status"])
+        ...
+        ...     result = client.step(MissionCtrlAction(action="FLAG(task_01, 'fabricated citation')"))
+        ...     print(f"reward={result.reward}, done={result.done}")
+
+    Example with Docker:
+        >>> client = MissionCtrlEnv.from_docker_image("missionctrl-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(MissionCtrlAction(action="APPROVE(task_02)"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: MissionCtrlAction) -> Dict:
+        """
+        Convert MissionCtrlAction to JSON payload for step message.
+
+        Args:
+            action: MissionCtrlAction instance with an ``action`` string.
+
+        Returns:
+            Dictionary suitable for JSON encoding and POSTing to /step.
+        """
+        return {
+            "action": action.action,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[MissionCtrlObservation]:
+        """
+        Parse server response into StepResult[MissionCtrlObservation].
+
+        Args:
+            payload: JSON response data from server.
+
+        Returns:
+            StepResult wrapping a MissionCtrlObservation.
+        """
+        obs_data = payload.get("observation", {})
+        observation = MissionCtrlObservation(
+            time_step=obs_data.get("time_step", 0),
+            max_steps=obs_data.get("max_steps", 5),
+            difficulty=obs_data.get("difficulty", "easy"),
+            tasks=obs_data.get("tasks", []),
+            hallucination_stats=obs_data.get("hallucination_stats", {}),
+            num_injected=obs_data.get("num_injected", 0),
+            available_actions=obs_data.get("available_actions", []),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request.
+
+        Returns:
+            State object with episode_id and step_count.
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

models.py

@@ -0,0 +1,63 @@
+"""
+Data models for the MissionCtrl AI Oversight Fleet Environment.
+
+Defines the typed Action and Observation classes used by the MissionCtrl
+EnvClient for structured interaction with the environment server.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class MissionCtrlAction(Action):
+    """Action for the MissionCtrl environment.
+
+    The overseer agent submits one action string per step.  Valid formats:
+      - APPROVE(task_id)
+      - REJECT(task_id, "reason")
+      - REDELEGATE(task_id, AgentName)
+      - FLAG(task_id, "evidence")
+      - ESCALATE(task_id)
+      - SYNTHESIZE_REPORT()
+      - NOOP
+    """
+
+    action: str = Field(
+        ...,
+        description=(
+            "The overseer action string, e.g. APPROVE(task_01) or "
+            "FLAG(task_03, \"fabricated citation detected\")"
+        ),
+    )
+
+
+class MissionCtrlObservation(Observation):
+    """Observation returned by the MissionCtrl environment after each step.
+
+    Contains the task board, hallucination statistics, and timing info
+    needed by the overseer agent to decide its next action.
+    """
+
+    time_step: int = Field(default=0, description="Current step number in the episode")
+    max_steps: int = Field(default=5, description="Maximum steps allowed in this episode")
+    difficulty: str = Field(default="easy", description="Difficulty tier: easy, medium, hard, special")
+
+    tasks: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="List of task dicts with id, title, status, output, etc.",
+    )
+    hallucination_stats: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Hallucination tracker: total_injected, total_caught, total_flags",
+    )
+    num_injected: int = Field(default=0, description="Number of injected hallucinations")
+    available_actions: List[str] = Field(
+        default_factory=list,
+        description="List of valid action format strings",
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional environment metadata",
+    )

server/app.py

@@ -8,11 +8,12 @@
 import os
 import sys
 from contextlib import asynccontextmanager
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, JSONResponse, Response
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
 from pydantic import BaseModel
 
 # ---------------------------------------------------------------------------
@@ -28,7 +29,7 @@
 # Logging — suppress noisy poll endpoints
 # ---------------------------------------------------------------------------
 class _PollFilter(logging.Filter):
-    _SUPPRESSED = ("/state", "/history", "/results", "/dashboard", "/health", "/favicon", "/apple-touch-icon")
+    _SUPPRESSED = ("/state", "/history", "/results", "/dashboard", "/health", "/logs", "/favicon", "/apple-touch-icon")
 
     def filter(self, record: logging.LogRecord) -> bool:
         msg = record.getMessage()
@@ -48,6 +49,8 @@ def filter(self, record: logging.LogRecord) -> bool:
 # ---------------------------------------------------------------------------
 _env = MissionCtrlEnvironment()
 _completed_results: List[Dict[str, Any]] = []  # Accumulated episode results across tiers
+HF_SPACE_URL = os.getenv("HF_SPACE_URL", "https://huggingface.co/spaces/Jit-fnc/missionctrl_env")
+HF_SPACE_LOGS_URL = os.getenv("HF_SPACE_LOGS_URL", f"{HF_SPACE_URL}?logs=container")
 
 # ---------------------------------------------------------------------------
 # Request / Response models
@@ -89,6 +92,7 @@ async def lifespan(_: FastAPI):
     ║     GET  /state      → Current observation (read-only)       ║
     ║     GET  /dashboard  → Live visualization UI                 ║
     ║     GET  /history    → Agent action history (JSON)           ║
+    ║     GET  /logs       → Redirect to HF container logs         ║
     ║                                                              ║
     ║   Tasks: easy, medium, hard, special                         ║
     ║                                                              ║
@@ -98,8 +102,14 @@ async def lifespan(_: FastAPI):
     ║                                                              ║
     ╚══════════════════════════════════════════════════════════════╝
     """
-    print(banner)
+    # Use sys.stderr for HF Spaces container log capture
+    sys.stderr.write(banner + "\n")
+    sys.stderr.flush()
     log.info("Server started — using persistent singleton environment")
+    log.info("Boot time: %s", datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC"))
+    log.info("Health: http://0.0.0.0:8000/health")
+    log.info("Dashboard: http://0.0.0.0:8000/dashboard")
+    sys.stderr.flush()
     yield
 
 
@@ -123,13 +133,20 @@ async def lifespan(_: FastAPI):
 # GET /
 # ---------------------------------------------------------------------------
 @app.get("/")
-async def root() -> Dict[str, Any]:
-    """Root endpoint — heartbeat for OpenEnv platform probes."""
+async def root():
+    """Root endpoint — redirect to dashboard for HF Spaces preview."""
+    return RedirectResponse(url="/dashboard", status_code=307)
+
+
+@app.get("/info")
+async def info() -> Dict[str, Any]:
+    """Info endpoint — heartbeat for OpenEnv platform probes."""
     return {
         "status": "ok",
         "name": "missionctrl",
         "version": "1.0.0",
-        "endpoints": ["/health", "/reset", "/step", "/state", "/dashboard", "/history"],
+        "endpoints": ["/health", "/reset", "/step", "/state", "/dashboard", "/history", "/logs"],
+        "logs_url": HF_SPACE_LOGS_URL,
     }
 
 
@@ -228,6 +245,24 @@ async def dashboard() -> HTMLResponse:
         return HTMLResponse(content=f.read())
 
 
+# ---------------------------------------------------------------------------
+# GET|HEAD /logs
+# ---------------------------------------------------------------------------
+@app.api_route("/logs", methods=["GET", "HEAD"])
+async def logs(redirect: bool = False):
+    """Return logs URL info; optionally redirect to the HF container logs page."""
+    if redirect:
+        return RedirectResponse(url=HF_SPACE_LOGS_URL, status_code=307)
+
+    return JSONResponse(
+        {
+            "status": "ok",
+            "logs_url": HF_SPACE_LOGS_URL,
+            "hint": "Open logs_url in a browser, or call /logs?redirect=1 to auto-redirect.",
+        }
+    )
+
+
 # ---------------------------------------------------------------------------
 # Favicon & Apple Touch Icon — suppress 404 noise
 # ---------------------------------------------------------------------------