Persist human Play-tab runs in the standard Playback format

Addresses PR #13's concern — saving human-play data for research — the
apples-to-apples way: a human run now produces the IDENTICAL artifact a
model run does, instead of a separate parallel format.

InteractiveSession (the Play tab's turn-stepped session) now emits a
standard Playback dir under the same PLAYBACK_ROOT model runs use:
turns.jsonl per-turn commands / signals / goal
minimap_turnNN.png per-turn frame (same prompt_v2 renderer as models)
messages.json per-turn transcript ({role,content,tool_calls})
manifest.json same shape run_level writes, tagged model=Human /
agent_type=Human
So the Battle Viewer (incl. its compare mode) and the leaderboard
treat human and LLM runs uniformly — human-vs-LLM comparison for free,
no separate schema to reconcile.

- record=True by default; record=False / playback_root= for tests.
- Abandoned sessions still finalize (viewable); never-played sessions
drop their empty dir.
- status() surfaces save_path; the Play tab shows it on game-over.

NOT taken from PR #13: the separate data/human_runs/ JSON format, the
per-session auto-append to results.csv, the data/results.csv reset, the
schema.py stub fallback, and the openra_rl_training shim stubs —
superseded by the proper vendoring already on main.

tests/test_human_labeling.py: +1 test asserting the standard Playback
layout + Human-tagged manifest; 25 green.

app.py

@@ -1167,6 +1167,11 @@ def _play_status_md(sess) -> str:
     line = f"**Turn {st['turn']}/{st['max_turns']}** · tick {st['tick']}"
     if st["done"]:
         line += f" · **{st['outcome'].upper()}** — game over"
+        if st.get("save_path"):
+            line += (
+                f"\n\n_Run saved (standard playback format): "
+                f"`{st['save_path']}`_"
+            )
     return line
 
 

openra_bench/human_labeling.py

@@ -468,7 +468,14 @@ class InteractiveSession:
         s.close()
     """
 
-    def __init__(self, compiled: Any, seed: int = 1):
+    def __init__(
+        self,
+        compiled: Any,
+        seed: int = 1,
+        record: bool = True,
+        playback_root: Any = None,
+        player: str = "Human",
+    ):
         from openra_rl_training.training.rust_env_pool import RustEnvPool
 
         from .eval_core import _scenario_to_tmp_yaml
@@ -492,6 +499,21 @@ class InteractiveSession:
         self.outcome = "draw"
         self.done = False
         self._closed = False
+        self.save_path: str | None = None
+        # Standard-playback recording: a human run produces the IDENTICAL
+        # artifact a model run does — a Playback dir (turns.jsonl,
+        # per-turn minimap PNGs, messages.json, manifest.json) under the
+        # same PLAYBACK_ROOT — so the Battle Viewer and leaderboard treat
+        # human and LLM runs apples-to-apples (no separate human format).
+        self._player = player
+        self._playback = None
+        self._finalized = False
+        self._history: list[dict] = []
+        self._issued = 0
+        self._pb_terrain = None
+        self._pb_explored: set = set()
+        if record:
+            self._setup_playback(playback_root)
 
     # A live engine session is a resource handle, not a value. Gradio's
     # `gr.State` deep-copies whatever it holds — and the RustEnvPool
@@ -506,7 +528,13 @@ class InteractiveSession:
 
     @classmethod
     def from_pack(
-        cls, pack_id: str, level: str = "easy", seed: int = 1
+        cls,
+        pack_id: str,
+        level: str = "easy",
+        seed: int = 1,
+        record: bool = True,
+        playback_root: Any = None,
+        player: str = "Human",
     ) -> "InteractiveSession":
         """Compile a pack by id and open a session on it."""
         from .scenarios import load_pack
@@ -515,7 +543,10 @@ class InteractiveSession:
         compiled = compile_level(
             load_pack(PACKS_DIR / f"{pack_id}.yaml"), level
         )
-        return cls(compiled, seed=seed)
+        return cls(
+            compiled, seed=seed, record=record,
+            playback_root=playback_root, player=player,
+        )
 
     @property
     def Command(self) -> Any:
@@ -545,8 +576,155 @@ class InteractiveSession:
             "outcome": self.outcome,
             "done": self.done,
             "tick": self._adapter.signals.game_tick,
+            "save_path": self.save_path,
         }
 
+    # ── Standard-playback recording ──────────────────────────────────
+    def _setup_playback(self, playback_root: Any) -> None:
+        """Open a Playback dir — the same one model runs use."""
+        try:
+            import os
+            from datetime import datetime, timezone
+            from pathlib import Path
+
+            from .playback import Playback
+
+            root = Path(
+                playback_root
+                or os.environ.get(
+                    "OPENRA_BENCH_PLAYBACK_ROOT",
+                    Path(__file__).resolve().parents[1] / "playback",
+                )
+            )
+            run_id = "human-" + datetime.now(timezone.utc).strftime(
+                "%Y%m%dT%H%M%SZ"
+            )
+            safe = "".join(
+                c if (c.isalnum() or c in "-_") else "-"
+                for c in self._player
+            )
+            pb = Playback(
+                root / f"{run_id}__{safe}",
+                cell=f"{self.compiled.pack_id}:{self.compiled.level}",
+                seed=self.seed,
+            )
+            pb.run_id, pb.model = run_id, self._player
+            self._playback = pb
+            self._history = [{
+                "role": "system",
+                "content": (
+                    f"Human-labeling session — {self.compiled.pack_id}:"
+                    f"{self.compiled.level} seed {self.seed}. Objective: "
+                    f"{self.objective or '(see briefing)'}"
+                ),
+            }]
+        except Exception:  # noqa: BLE001 — recording never breaks play
+            self._playback = None
+
+    def _pb_frame(self, rs: dict) -> "str | None":
+        """Per-turn minimap PNG (b64) via the SAME renderer model
+        playback uses, so saved human frames match model frames."""
+        try:
+            from .minimap import terrain_png_for
+
+            if self._pb_terrain is None:
+                self._pb_terrain = terrain_png_for(
+                    self.compiled.scenario.base_map
+                )
+            from .prompt_v2 import minimap_b64 as _v2_mm
+
+            png = _v2_mm(
+                rs, self._pb_terrain, self._pb_explored,
+                constant_colors=self.compiled.level in ("easy", "medium"),
+            )
+            if png is None:
+                from .agent import _render_minimap_b64
+
+                png = _render_minimap_b64(rs, self._pb_terrain)
+            return png
+        except Exception:  # noqa: BLE001
+            return None
+
+    def _record_turn_playback(self, actions, calls, cmds, ctx) -> None:
+        """Append one turn to the Playback + the message transcript."""
+        if self._playback is None:
+            return
+        from .goal_tracker import turn_goal
+
+        rs = self._adapter.render_state()
+        self._issued += len(cmds)
+        self._playback.record_turn(
+            self.turn, rs, cmds, self._adapter.signals,
+            self._pb_frame(rs),
+            goal=turn_goal(self.compiled.win_condition, ctx),
+        )
+        # Transcript turn — same {role, content, tool_calls} shape a
+        # ModelAgent writes, so messages.json is uniform across human
+        # and LLM runs.
+        self._history.append(
+            {"role": "user", "content": HumanController._briefing(rs)}
+        )
+        self._history.append({
+            "role": "assistant",
+            "content": "; ".join(a.describe() for a in actions) or "observe",
+            "reasoning": "; ".join(a.note for a in actions if a.note),
+            "tool_calls": [
+                {
+                    "id": f"h{i}", "type": "function",
+                    "function": {
+                        "name": c["name"], "arguments": c["arguments"],
+                    },
+                }
+                for i, c in enumerate(calls)
+            ],
+        })
+        for i in range(len(calls)):
+            self._history.append(
+                {"role": "tool", "tool_call_id": f"h{i}", "content": "ok"}
+            )
+
+    def _finalize_playback(self, ctx) -> None:
+        """Write messages.json + manifest.json — the same manifest shape
+        `run_level` writes for a model run, tagged as a human run."""
+        if self._playback is None or self._finalized:
+            return
+        self._finalized = True
+        from .goal_tracker import turn_goal
+
+        final_goal = turn_goal(self.compiled.win_condition, ctx)
+        sig = self._adapter.signals
+        try:
+            self._playback.write_messages(self._history)
+            self._playback.finalize({
+                "scenario": f"{self.compiled.pack_id}:{self.compiled.level}",
+                "pack_id": self.compiled.pack_id,
+                "level": self.compiled.level,
+                "capability": self.compiled.meta.capability,
+                "run_id": self._playback.run_id,
+                "model": self._playback.model,
+                "agent_type": "Human",
+                "seed": self.seed,
+                "outcome": self.outcome,
+                "turns": self.turn,
+                "max_turns": self.max_turns,
+                "actions_issued": self._issued,
+                "actions_warned": 0,
+                "agent_stats": {"turns": self.turn},
+                "objective_progress": final_goal.get(
+                    "objective_progress", 0.0
+                ),
+                "reward_vector": final_goal.get("reward_vector", {}),
+                "signals": {
+                    "economy_value": sig.cash + sig.resources,
+                    "explored_percent": round(sig.explored_percent, 2),
+                    "units_killed": sig.units_killed,
+                    "units_lost": sig.units_lost,
+                },
+            })
+            self.save_path = str(self._playback.dir)
+        except Exception:  # noqa: BLE001
+            pass
+
     def submit_turn(self, actions: "list[HumanAction]") -> dict:
         """Advance one decision turn with the human's gestures. Mirrors
         `run_level`'s per-turn body. Returns the updated `status()`."""
@@ -592,6 +770,10 @@ class InteractiveSession:
             or self.turn >= self.max_turns
         ):
             self.done = True
+        # Standard-playback recording — log this turn, finalize on done.
+        self._record_turn_playback(actions or [], calls, cmds, ctx)
+        if self.done:
+            self._finalize_playback(ctx)
         return self.status()
 
     def close(self) -> None:
@@ -599,6 +781,34 @@ class InteractiveSession:
         if self._closed:
             return
         self._closed = True
+        # An abandoned run (closed before game-over) is still finalized
+        # so its Playback dir carries a manifest and stays viewable.
+        if (
+            self._playback is not None
+            and not self._finalized
+            and self.turn > 0
+        ):
+            try:
+                from .scenarios.win_conditions import WinContext
+
+                self._finalize_playback(
+                    WinContext(
+                        signals=self._adapter.signals,
+                        render_state=self._adapter.render_state(),
+                    )
+                )
+            except Exception:  # noqa: BLE001
+                pass
+        elif self._playback is not None and self.turn == 0:
+            # Never-played recorded session — drop the empty dir rather
+            # than littering the playback root.
+            import shutil
+
+            try:
+                self._playback._turns_fh.close()
+            except Exception:  # noqa: BLE001
+                pass
+            shutil.rmtree(self._playback.dir, ignore_errors=True)
         try:
             self._pool.release(self._env)
             self._pool.shutdown()

tests/test_human_labeling.py

@@ -339,7 +339,7 @@ def test_interactive_session_steps_turn_by_turn():
     compiled = _smallest_easy_pack()
     assert compiled is not None
 
-    sess = InteractiveSession(compiled, seed=1)
+    sess = InteractiveSession(compiled, seed=1, record=False)
     try:
         # The observation is a real render_state — what the LLM sees.
         rs = sess.render_state()
@@ -372,7 +372,9 @@ def test_interactive_session_from_pack():
     from openra_bench.human_labeling import InteractiveSession
 
     compiled = _smallest_easy_pack()
-    sess = InteractiveSession.from_pack(compiled.pack_id, "easy", seed=2)
+    sess = InteractiveSession.from_pack(
+        compiled.pack_id, "easy", seed=2, record=False
+    )
     try:
         assert sess.seed == 2
         assert sess.Command is not None
@@ -387,3 +389,51 @@ def test_interactive_session_from_pack():
             assert sess.turn == 1
     finally:
         sess.close()
+
+
+def test_interactive_session_emits_standard_playback(tmp_path):
+    """A recorded human session produces the SAME Playback artifact a
+    model run does — turns.jsonl + per-turn minimap PNGs + messages.json
+    + a manifest — so the Battle Viewer / leaderboard treat human and
+    LLM runs apples-to-apples."""
+    import json
+    from pathlib import Path
+
+    from openra_bench.human_labeling import InteractiveSession
+
+    compiled = _smallest_easy_pack()
+    assert compiled is not None
+
+    sess = InteractiveSession(
+        compiled, seed=1, record=True, playback_root=tmp_path,
+        player="Human",
+    )
+    try:
+        guard = compiled.max_turns + 5
+        steps = 0
+        while not sess.done and steps < guard:
+            sess.submit_turn([HumanAction(mode="observe")])
+            steps += 1
+        assert sess.done
+        save = sess.status()["save_path"]
+        assert save, "a finished recorded session must report save_path"
+        run_dir = Path(save)
+        # Standard Playback layout — identical to a model run's.
+        assert (run_dir / "turns.jsonl").is_file()
+        assert (run_dir / "messages.json").is_file()
+        manifest = json.loads((run_dir / "manifest.json").read_text())
+        assert manifest["model"] == "Human"
+        assert manifest["agent_type"] == "Human"
+        assert manifest["pack_id"] == compiled.pack_id
+        assert manifest["outcome"] in ("win", "loss", "draw")
+        assert manifest["turns"] == sess.turn
+        # Per-turn minimap PNG frames were written.
+        assert list(run_dir.glob("minimap_turn*.png"))
+        # turns.jsonl has one record per turn.
+        lines = [
+            ln for ln in (run_dir / "turns.jsonl").read_text().splitlines()
+            if ln.strip()
+        ]
+        assert len(lines) == sess.turn
+    finally:
+        sess.close()