[kimi] Add Pip familiar state to agent_state messages (#676) (#738)

src/infrastructure/presence.py

@@ -5,9 +5,45 @@ into the camelCase world-state payload consumed by the Workshop 3D renderer
 and WebSocket gateway.
 """
 
+import logging
 import time
 from datetime import UTC, datetime
 
+logger = logging.getLogger(__name__)
+
+# Default Pip familiar state (used when familiar module unavailable)
+DEFAULT_PIP_STATE = {
+    "name": "Pip",
+    "mood": "sleepy",
+    "energy": 0.5,
+    "color": "0x00b450",  # emerald green
+    "trail_color": "0xdaa520",  # gold
+}
+
+
+def _get_familiar_state() -> dict:
+    """Get Pip familiar state from familiar module, with graceful fallback.
+
+    Returns a dict with name, mood, energy, color, and trail_color.
+    Falls back to default state if familiar module unavailable or raises.
+    """
+    try:
+        from timmy.familiar import pip_familiar
+
+        snapshot = pip_familiar.snapshot()
+        # Map PipSnapshot fields to the expected agent_state format
+        return {
+            "name": snapshot.name,
+            "mood": snapshot.state,
+            "energy": DEFAULT_PIP_STATE["energy"],  # Pip doesn't track energy yet
+            "color": DEFAULT_PIP_STATE["color"],
+            "trail_color": DEFAULT_PIP_STATE["trail_color"],
+        }
+    except Exception as exc:
+        logger.warning("Familiar state unavailable, using default: %s", exc)
+        return DEFAULT_PIP_STATE.copy()
+
+
 # Valid bark styles for Matrix protocol
 BARK_STYLES = {"speech", "thought", "whisper", "shout"}
 
@@ -200,6 +236,7 @@ def produce_agent_state(agent_id: str, presence: dict) -> dict:
             "mood": presence.get("mood", "calm"),
             "energy": presence.get("energy", 0.5),
             "bark": presence.get("bark", ""),
+            "familiar": _get_familiar_state(),
         },
         "ts": int(time.time()),
     }