feat(agents): extract_self_belief parser for find-your-body SELF: reports

proteus/game/agents/parsing.py

@@ -16,6 +16,7 @@ import re
 
 _ACTION_FIELD = re.compile(r"ACTION\s*:\s*([^\n\r]+)", re.IGNORECASE)
 _WORD = re.compile(r"[a-zA-Z]+")
+_SELF_FIELD = re.compile(r"SELF\s*:\s*(\d+)", re.IGNORECASE)
 
 
 def extract_action(text: str, valid: list[str]) -> str | None:
@@ -47,3 +48,26 @@ def extract_action(text: str, valid: list[str]) -> str | None:
             return w
 
     return None
+
+
+def extract_self_belief(text: str, n_candidates: int) -> int | None:
+    """Return the last in-range ``SELF: <i>`` index in *text*, else ``None``.
+
+    The errand_runner find-your-body discovery lets the model append
+    ``SELF: <0..n_candidates-1>`` to report which identical candidate it
+    believes is its own body. The last such report wins (the model may revise
+    mid-reasoning). Out-of-range or absent reports yield ``None``. This does not
+    affect movement parsing (:func:`extract_action`).
+
+    Args:
+        text: Raw LLM output.
+        n_candidates: Number of candidate bodies (valid indices ``0..n-1``).
+
+    Returns:
+        The believed self-index, or ``None``.
+    """
+    for raw in reversed(_SELF_FIELD.findall(text)):
+        i = int(raw)
+        if 0 <= i < n_candidates:
+            return i
+    return None

tests/agents/test_self_belief.py

@@ -0,0 +1,26 @@
+# tests/agents/test_self_belief.py
+"""extract_self_belief parses the optional `SELF: <i>` body-identity report.
+
+Used by errand_runner find-your-body discovery; movement parsing is untouched.
+"""
+from proteus.game.agents.parsing import extract_self_belief
+
+
+def test_parses_valid_index():
+    assert extract_self_belief("I think SELF: 2\nACTION: up", 3) == 2
+
+
+def test_last_self_wins():
+    assert extract_self_belief("SELF: 0 ... on reflection SELF: 1", 3) == 1
+
+
+def test_out_of_range_rejected():
+    assert extract_self_belief("SELF: 5", 3) is None
+
+
+def test_absent_returns_none():
+    assert extract_self_belief("ACTION: up", 3) is None
+
+
+def test_case_insensitive_and_spacing():
+    assert extract_self_belief("self :  0", 3) == 0