feat(cp5): HumanAgent act path + WASD parsing + reprompt (I/O-injected)

proteus/agents/__init__.py

@@ -1,6 +1,7 @@
 """proteus.agents — slim LLM agent abstraction (no forfeit/stake/risk)."""
 
 from proteus.agents.base import Agent, ActResult, ProbeResult
+from proteus.agents.human import HumanAgent
 from proteus.agents.vanilla import VanillaAgent
 
-__all__ = ["Agent", "ActResult", "ProbeResult", "VanillaAgent"]
+__all__ = ["Agent", "ActResult", "ProbeResult", "HumanAgent", "VanillaAgent"]

proteus/agents/human.py

@@ -0,0 +1,83 @@
+"""HumanAgent — a stdin-driven Agent so a person plays through the same SessionRunner.
+
+Routing a human through the identical SessionRunner makes the resulting
+SessionTrace schema-identical to an LLM trace, so the two compare directly
+(the human-baseline foundation, spec §10). The agent is I/O-injected
+(input_fn / output_fn) so human play is testable headlessly with a scripted
+input stream — no TTY, no network.
+
+Fairness note: the live view is the ASCII observation the LLM also sees; the
+truecolor / PNG renderers are reserved for post-hoc replay (proteus.viz), so a
+human baseline reads exactly what the model reads.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Callable, Optional
+
+from proteus.agents.base import Agent, ActResult, ProbeResult
+
+# Single-key shortcuts -> canonical action strings (WASD).
+_SHORTCUTS = {"w": "up", "a": "left", "s": "down", "d": "right"}
+
+
+class HumanAgent(Agent):
+    """An Agent driven by a person via injected input/output callables.
+
+    Args:
+        input_fn: Reads one line from the human (defaults to builtins.input,
+            resolved lazily so tests can monkeypatch builtins.input).
+        output_fn: Shows a line to the human (defaults to builtins.print).
+    """
+
+    def __init__(
+        self,
+        input_fn: Optional[Callable[[str], str]] = None,
+        output_fn: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        # Resolve builtins at construction time (not as default-arg values, which
+        # would capture the pre-monkeypatch references at import time).
+        self._input = input_fn if input_fn is not None else builtins.input
+        self._output = output_fn if output_fn is not None else builtins.print
+
+    @property
+    def name(self) -> str:
+        return "human"
+
+    def act(
+        self,
+        observation: str,
+        available_actions: list[str],
+        system_prompt: str,
+    ) -> ActResult:
+        self._output(observation)
+        action, raw = self._read_action(available_actions)
+        return ActResult(action=action, reasoning="", raw_text=raw)
+
+    def probe(
+        self,
+        observation: str,
+        question: str,
+        system_prompt: str,
+    ) -> ProbeResult:
+        # Implemented in Task 2.
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        return None
+
+    def _read_action(self, available_actions: list[str]) -> tuple[str, str]:
+        """Prompt until a valid action is entered; return (action, raw_input)."""
+        valid = {a.lower() for a in available_actions}
+        prompt = f"action [{'/'.join(available_actions)} | wasd]> "
+        while True:
+            raw = self._input(prompt).strip()
+            token = raw.lower()
+            action = _SHORTCUTS.get(token, token)
+            if action in valid:
+                return action, raw
+            self._output(
+                f"invalid input {raw!r}; choose one of "
+                f"{', '.join(available_actions)} (or wasd)."
+            )

tests/agents/test_human.py

@@ -0,0 +1,60 @@
+from proteus.agents import HumanAgent
+from proteus.agents.base import ActResult
+
+_ACTIONS = ["up", "down", "left", "right", "stay"]
+
+
+def _scripted(seq):
+    """Return an input_fn that yields the given strings in order."""
+    it = iter(seq)
+    return lambda prompt="": next(it)
+
+
+def test_act_parses_plain_action():
+    out = []
+    agent = HumanAgent(input_fn=_scripted(["up"]), output_fn=out.append)
+    result = agent.act("OBSERVATION", _ACTIONS, "SYSTEM")
+    assert isinstance(result, ActResult)
+    assert result.action == "up"
+    assert result.reasoning == ""
+    assert result.raw_text == "up"
+    assert result.input_tokens == 0
+    assert result.output_tokens == 0
+    assert result.thinking_tokens == 0
+    # The observation was shown to the human.
+    assert any("OBSERVATION" in line for line in out)
+
+
+def test_act_maps_wasd_shortcuts():
+    agent = HumanAgent(input_fn=_scripted(["w"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "up"
+    agent = HumanAgent(input_fn=_scripted(["a"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "left"
+    agent = HumanAgent(input_fn=_scripted(["s"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "down"
+    agent = HumanAgent(input_fn=_scripted(["d"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "right"
+
+
+def test_act_is_case_and_whitespace_insensitive():
+    agent = HumanAgent(input_fn=_scripted(["  UP  "]), output_fn=lambda s: None)
+    result = agent.act("o", _ACTIONS, "s")
+    assert result.action == "up"
+    assert result.raw_text == "UP"  # stripped, original casing preserved
+
+
+def test_act_reprompts_on_invalid_then_accepts():
+    out = []
+    agent = HumanAgent(input_fn=_scripted(["nope", "diagonal", "right"]), output_fn=out.append)
+    result = agent.act("o", _ACTIONS, "s")
+    assert result.action == "right"
+    # Two invalid inputs produced two guidance messages.
+    assert sum("invalid" in line for line in out) == 2
+
+
+def test_name_is_human():
+    assert HumanAgent().name == "human"
+
+
+def test_reset_is_noop():
+    assert HumanAgent().reset() is None