agentvibes 5.12.0 → 5.13.0

package/.claude/hooks/party-set-room.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/party-set-room.sh
+#
+# AgentVibes - record the chosen (non-default) party room for this session.
+#
+# party-stage-roster.py broadcasts the DEFAULT installed-agent room unless it
+# knows a specific room was chosen. This tiny helper is the AgentVibes-side
+# mechanism for recording that choice: it writes the active-room state file
+#
+#   ~/.agentvibes/party-active-<sessionid>.json  =  {"group":"<group-id>"}
+#
+# keyed by the canonical routing session id (av_session_id = basename of
+# CLAUDE_PROJECT_DIR). party-stage-roster.py reads this file and passes the
+# group to resolve_party.py as --party, so a chosen non-default room gets
+# broadcast instead of the default.
+#
+# EXTENSION POINT (we do NOT edit the BMAD skill): a party skill can call this
+# from its user-config `activation_steps_append` when the user picks a room --
+# that is the sanctioned way to wire this in without touching BMAD-owned files.
+#
+# Non-destructive: only creates ~/.agentvibes (mkdir -p) and writes/overwrites
+# the one per-session state file it owns. Touches no user config.
+#
+# Usage: party-set-room.sh <group-id>
+#        party-set-room.sh --clear      # remove the state file (back to default)
+#
+# bash-3.2 safe (macOS default bash).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./session-id.sh
+source "$SCRIPT_DIR/session-id.sh"
+
+GROUP="${1:-}"
+if [[ -z "$GROUP" ]]; then
+  echo "usage: party-set-room.sh <group-id> | --clear" >&2
+  exit 2
+fi
+
+SESSION_ID="$(av_session_id "${CLAUDE_PROJECT_DIR:-$PWD}")"
+STATE_DIR="$HOME/.agentvibes"
+STATE_FILE="$STATE_DIR/party-active-${SESSION_ID}.json"
+
+mkdir -p "$STATE_DIR"
+
+if [[ "$GROUP" == "--clear" ]]; then
+  rm -f "$STATE_FILE"
+  # Also clear the stage-on-first-speak idempotency flag so the next party
+  # re-broadcasts its cast (this is the manual party-reset path).
+  rm -f "$STATE_DIR/staged-${SESSION_ID}.flag"
+  echo "party-set-room: cleared active room for session '$SESSION_ID' (back to default)."
+  exit 0
+fi
+
+# Validate the group id: a group id is a slug (letters/digits/._-). Reject
+# anything else so we never write attacker-controlled JSON.
+if [[ ! "$GROUP" =~ ^[A-Za-z0-9._-]+$ ]]; then
+  echo "party-set-room: invalid group id '$GROUP' (allowed: A-Za-z0-9._-)" >&2
+  exit 2
+fi
+
+# Write atomically so a concurrent reader never sees a half-written file.
+_tmp="$(mktemp "$STATE_DIR/party-active-${SESSION_ID}.XXXXXX")" || exit 1
+trap 'rm -f "$_tmp"' EXIT
+printf '{"group":"%s"}\n' "$GROUP" > "$_tmp"
+mv "$_tmp" "$STATE_FILE"
+trap - EXIT
+
+echo "party-set-room: session '$SESSION_ID' room set to '$GROUP'."

package/.claude/hooks/party-stage-roster.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Broadcast a BMAD party's cast to an AgentVibes receiver (best-effort doorbell).
+
+A receiver normally learns an avatar only when it speaks (one /speak event per
+line). This doorbell stages the WHOLE cast up front: it resolves the active
+party roster (via BMAD's read-only ``resolve_party.py``), joins each member to
+its saved voice/avatar, and POSTs the result to a receiver's ``/stage-roster``
+endpoint keyed by the SESSION id. Any receiver that implements ``/stage-roster``
+can then paint the labelled, voiced cast at once; a receiver that doesn't (or a
+down/absent one) simply never hears the doorbell and the party runs unchanged.
+
+Session key
+-----------
+The broadcast is keyed by the canonical routing SESSION id -- ``basename`` of
+``CLAUDE_PROJECT_DIR`` (falling back to ``--project-root``), slugified the same
+way ``.claude/hooks/session-id.sh :: av_session_id`` slugifies it -- plus the
+``--session-suffix`` (default ``bmad-party-mode``). The suffix stages the party
+on its OWN session, distinct from the plain-TTS session for the same project.
+
+Open-cast vs fixed-cast (the forward-compat contract)
+-----------------------------------------------------
+  * Fixed-cast (members present): POST
+      {"session","project","roster":[{name,agentId,voice,role?,avatarId?}]}
+  * Open-cast (resolve_party sets ``open_cast`` when a room lists no fixed
+    members, only a freeform ``scene`` theme): POST
+      {"session","project","roster":[...anchors if any...],
+       "openCast":true,"room":{"id","name","scene"}}
+    Open-cast rooms are broadcast rather than skipped, so a receiver that
+    understands the room theme has everything it needs to render it.
+
+``project`` is sent as a back-compat alias of ``session`` (current receivers key
+on ``project``).
+
+Best-effort contract
+--------------------
+Stdlib only (urllib). Any failure -- resolver error, connection refused, 404,
+timeout -- prints a benign note to stderr and returns 0. A down or absent
+receiver must NEVER block or fail the party.
+
+  party-stage-roster.py --project-root P [--skill S] [--party ID]
+                        [--session-suffix bmad-party-mode] [--url http://127.0.0.1:3747]
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+
+def _resolve_roster(project_root: Path, skill_root: Path, party):
+    """Run BMAD's resolve_party.py (READ-ONLY) and return its parsed JSON, or None."""
+    script = skill_root / "scripts" / "resolve_party.py"
+    cmd = [sys.executable, str(script), "--project-root", str(project_root), "--skill", str(skill_root)]
+    if party:
+        cmd += ["--party", party]
+    try:
+        # encoding+errors are REQUIRED on Windows: text=True defaults to cp1252,
+        # which crashes on the non-Latin icon bytes the resolver can emit.
+        # PYTHONUTF8 forces the child to write UTF-8 rather than crash.
+        child_env = {**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"}
+        out = subprocess.run(cmd, capture_output=True, text=True,
+                             encoding="utf-8", errors="replace",
+                             env=child_env, timeout=60)
+    except (OSError, subprocess.SubprocessError) as e:
+        sys.stderr.write(f"stage-roster: resolve_party failed to run: {e}\n")
+        return None
+    if out.returncode != 0 or not out.stdout.strip():
+        sys.stderr.write("stage-roster: resolve_party returned nothing usable\n")
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        sys.stderr.write("stage-roster: resolve_party output was not JSON\n")
+        return None
+
+
+def _home_dir() -> Path:
+    """User home, resilient to the launch environment.
+
+    os.path.expanduser("~") returns "~" unchanged when USERPROFILE and
+    HOMEDRIVE/HOMEPATH are all unset -- which is exactly the env some launchers
+    hand these scripts. Check the vars actually present, Windows-then-POSIX.
+    """
+    for var in ("USERPROFILE", "HOME"):
+        v = os.environ.get(var)
+        if v:
+            return Path(v)
+    hd, hp = os.environ.get("HOMEDRIVE"), os.environ.get("HOMEPATH")
+    if hd and hp:
+        return Path(hd + hp)
+    return Path(os.path.expanduser("~"))
+
+
+def _find_skill_root(project_root: Path):
+    """Locate the installed bmad-party-mode skill dir (project-local, else global).
+
+    Returns a Path whose scripts/resolve_party.py exists, or None.
+    """
+    candidates = [
+        project_root / ".claude" / "skills" / "bmad-party-mode",
+        _home_dir() / ".claude" / "skills" / "bmad-party-mode",
+    ]
+    for c in candidates:
+        if (c / "scripts" / "resolve_party.py").exists():
+            return c
+    return None
+
+
+def _load_json_map(name: str) -> dict:
+    """Read a ~/.agentvibes/<name> JSON map. {} if absent or unreadable."""
+    path = _home_dir() / ".agentvibes" / name
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _voice_for(code: str, vmap: dict) -> str:
+    """Saved voice string for an agent code, or '' if none.
+
+    Prefers the richer agents[code].voice; falls back to the flat
+    voiceMap[code] (older shape). Both key by the canonical agent code.
+    """
+    agents = vmap.get("agents") or {}
+    entry = agents.get(code)
+    if isinstance(entry, dict) and entry.get("voice"):
+        return str(entry["voice"])
+    flat = vmap.get("voiceMap") or {}
+    if isinstance(flat.get(code), str):
+        return flat[code]
+    return ""
+
+
+def _avatar_for(code: str, vmap: dict, amap: dict) -> str:
+    """Saved avatarId for an agent code, or '' if none.
+
+    The dedicated avatar map wins; the voice map's agents[id].avatarId is a
+    legacy fallback (honoured if present).
+    """
+    ag = (amap.get("agents") or {}) if isinstance(amap, dict) else {}
+    entry = ag.get(code)
+    if isinstance(entry, dict) and entry.get("avatarId"):
+        return str(entry["avatarId"])
+    agents = vmap.get("agents") or {}
+    ventry = agents.get(code)
+    if isinstance(ventry, dict) and ventry.get("avatarId"):
+        return str(ventry["avatarId"])
+    return ""
+
+
+def _session_key(project_root: Path) -> str:
+    """Canonical routing SESSION id -- the same one the TTS forward paths send.
+
+    Mirrors .claude/hooks/session-id.sh :: av_session_id: basename of
+    CLAUDE_PROJECT_DIR (the real user project) when set, else --project-root,
+    slugified so the id is a safe JSON string and a stable receiver map key.
+    """
+    cpd = os.environ.get("CLAUDE_PROJECT_DIR", "").strip()
+    base = Path(cpd) if cpd else project_root
+    name = base.name or "unknown"
+    # Slugify to match av_session_id: collapse anything outside [A-Za-z0-9._-]
+    # to '-', then trim leading/trailing dashes.
+    name = re.sub(r"[^A-Za-z0-9._-]", "-", name).strip("-")
+    return name or "unknown"
+
+
+def _active_party(session_key: str, explicit):
+    """Resolve which room to stage.
+
+    Explicit --party wins. Otherwise read the AgentVibes-side active-room state
+    file ~/.agentvibes/party-active-<sessionid>.json = {"group": "<id>"} (written
+    by party-set-room.sh). If neither is present, return None so the DEFAULT
+    party resolves (the common installed-agent room).
+    """
+    if explicit:
+        return explicit
+    path = _home_dir() / ".agentvibes" / f"party-active-{session_key}.json"
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if isinstance(data, dict):
+        group = data.get("group")
+        if isinstance(group, str) and group.strip():
+            return group.strip()
+    return None
+
+
+def build_roster(resolved: dict, vmap: dict, amap: dict):
+    """Join resolver members to voices/avatars. Returns (roster, skipped_names)."""
+    members = resolved.get("members") or []
+    roster, skipped = [], []
+    for m in members:
+        code = m.get("code") or ""
+        name = m.get("name") or code or "Agent"
+        voice = _voice_for(code, vmap)
+        if not voice:
+            # Without a voice string the member can't key-match a later /speak
+            # event, so staging it would orphan an avatar -- skip it.
+            skipped.append(name)
+            continue
+        member = {"name": name, "agentId": code, "voice": voice}
+        title = (m.get("title") or "").strip()
+        if title:
+            member["role"] = title
+        avatar = _avatar_for(code, vmap, amap)
+        if avatar:
+            member["avatarId"] = avatar
+        roster.append(member)
+    return roster, skipped
+
+
+def post_payload(url: str, payload: dict):
+    """POST the payload to /stage-roster. Returns (ok, message)."""
+    body = json.dumps(payload).encode("utf-8")
+    base = url.rstrip("/")
+    req = urllib.request.Request(
+        base + "/stage-roster",
+        data=body,
+        headers={"Content-Type": "application/json", "Origin": base},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return True, resp.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        return False, f"HTTP {e.code}: {e.read().decode('utf-8', 'replace')[:200]}"
+    except (urllib.error.URLError, OSError) as e:
+        # Receiver not running / unreachable -- benign; the party runs regardless.
+        return False, f"could not reach receiver ({e}); is a receiver up?"
+
+
+def _default_url() -> str:
+    port = (os.environ.get("AGENTVIBES_TH_PORT")
+            or os.environ.get("TALKING_HEAD_PORT")
+            or "3747").strip()
+    if not port.isdigit():
+        port = "3747"
+    return f"http://127.0.0.1:{port}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Broadcast a BMAD party cast to an AgentVibes receiver.")
+    ap.add_argument("--project-root", required=True)
+    ap.add_argument("--skill", default=None,
+                    help="Path to the bmad-party-mode skill dir (auto-located if omitted)")
+    ap.add_argument("--party", default=None, help="Explicit group id (wins over the active-room file)")
+    ap.add_argument("--session-suffix", "--coin-suffix", dest="session_suffix",
+                    default="bmad-party-mode",
+                    help="Append '-<suffix>' to the session key so the party stages on its "
+                         "OWN session (default: bmad-party-mode).")
+    ap.add_argument("--url", default=None)
+    args = ap.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+
+    skill_root = Path(args.skill).resolve() if args.skill else _find_skill_root(project_root)
+    if skill_root is None:
+        sys.stderr.write("stage-roster: bmad-party-mode skill not found -- nothing to stage.\n")
+        return 0
+
+    session = _session_key(project_root)
+    party = _active_party(session, args.party)
+
+    resolved = _resolve_roster(project_root, skill_root, party)
+    if resolved is None:
+        return 0  # resolver failure already warned; never break the party
+
+    suffix = (args.session_suffix or "").strip().strip("-")
+    session_key = f"{session}-{suffix}" if suffix else session
+
+    vmap = _load_json_map("bmad-voice-map.json")
+    amap = _load_json_map("bmad-avatar-map.json")
+    roster, skipped = build_roster(resolved, vmap, amap)
+    if skipped:
+        sys.stderr.write(f"stage-roster: skipped (no saved voice): {', '.join(skipped)}\n")
+
+    open_cast = bool(resolved.get("open_cast"))
+
+    if open_cast:
+        # Broadcast open-cast rooms rather than skipping them: the room theme is
+        # all a receiver needs to render the scene.
+        room = {"id": resolved.get("active", ""), "name": resolved.get("name", "")}
+        scene = resolved.get("scene")
+        if scene:
+            room["scene"] = scene
+        payload = {"session": session_key, "project": session_key,
+                   "roster": roster, "openCast": True, "room": room}
+    else:
+        if not roster:
+            sys.stderr.write("stage-roster: no members had a saved voice -- nothing to stage.\n")
+            return 0
+        payload = {"session": session_key, "project": session_key, "roster": roster}
+
+    # Test hook: capture the exact payload to a file instead of hitting the
+    # network, so the hermetic bats suite can assert the wire shape.
+    capture = os.environ.get("AGENTVIBES_STAGE_CAPTURE", "").strip()
+    if capture:
+        try:
+            Path(capture).write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+        except OSError as e:
+            sys.stderr.write(f"stage-roster: could not write capture file: {e}\n")
+        print(f"stage-roster: captured payload for '{session_key}' -> {capture}")
+        return 0
+
+    url = args.url or _default_url()
+    ok, msg = post_payload(url, payload)
+    kind = "open-cast" if open_cast else f"{len(roster)} member(s)"
+    if ok:
+        print(f"stage-roster: staged {kind} for '{session_key}' -> {msg.strip()}")
+    else:
+        print(f"stage-roster: {msg}")
+    return 0  # benign: a down receiver must never block the party
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/hooks/personality-manager.sh

@@ -62,6 +62,17 @@ fi
 
 PERSONALITY_FILE="$CLAUDE_DIR/tts-personality.txt"
 
+# Source the generated Provider Catalog (bash-3.2-safe SSOT accessors) when present.
+# FAIL-SAFE: consumers probe `type catalog_* >/dev/null 2>&1` and fall back to the
+# legacy hardcoded literal when the artifact is missing (installed-tree skew) —
+# mirrors voice-manager.sh's identical pattern (AVI-S9.3/9.4).
+_load_provider_catalog() {
+  if [[ -f "$SCRIPT_DIR/provider-catalog.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/provider-catalog.sh" 2>/dev/null || true
+  fi
+}
+
 # Function to get personality data from markdown file
 get_personality_data() {
   local personality="$1"
@@ -200,8 +211,14 @@ case "$1" in
       # Try to get Piper-specific voice first
       ASSIGNED_VOICE=$(get_personality_data "$PERSONALITY" "piper_voice")
       if [[ -z "$ASSIGNED_VOICE" ]]; then
-        # Fallback to default Piper voice
-        ASSIGNED_VOICE="en_US-lessac-medium"
+        # Fallback to default Piper voice — sourced from the generated Provider
+        # Catalog SSOT (AVI-S9.4). FAIL-SAFE: legacy literal if artifact missing.
+        _load_provider_catalog
+        if type catalog_default_voice >/dev/null 2>&1; then
+          ASSIGNED_VOICE="$(catalog_default_voice piper)"
+        else
+          ASSIGNED_VOICE="en_US-lessac-medium"
+        fi
       fi
     else
       # Use Piper voice (reads from piper_voice: field)

package/.claude/hooks/piper-voice-manager.sh

@@ -296,6 +296,7 @@ patch_libritts_speaker_names() {
   # Find voice-assignments.json relative to this script (SCRIPT_DIR/../.. = project root)
   local script_dir
   script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  source "$script_dir/python-resolver.sh"
   local project_root
   project_root="$(cd "$script_dir/../.." 2>/dev/null && pwd)"
   local catalog="$project_root/voice-assignments.json"
@@ -315,8 +316,8 @@ patch_libritts_speaker_names() {
   fi
 
   # Check if already patched (first key doesn't start with 'p' + digits)
-  if command -v python3 &>/dev/null; then
-    python3 -c "
+  if [[ -n "$PYTHON_BIN" ]]; then
+    "$PYTHON_BIN" -c "
 import json, sys
 
 json_path = sys.argv[1]

package/.claude/hooks/play-tts-agentvibes-receiver-for-voiceless-connections.sh

@@ -14,7 +14,7 @@
 set -euo pipefail
 
 TEXT="${1:-}"
-VOICE="${2:-en_US-lessac-medium}"
+VOICE="${2:-}"
 AGENT_NAME="${3:-default}"
 
 # Validate required input
@@ -26,8 +26,27 @@ fi
 
 # Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/python-resolver.sh"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
+# Default voice: prefer the Provider Catalog's piper default (AVI-S9.6 AC3,
+# design row 23), falling back to the legacy literal if the generated catalog
+# artifact is missing (installed-tree skew). NOTE: any voice-format allowlist
+# added to this receiver in the future must stay independent of the catalog —
+# a security allowlist is deliberately narrower than the full inventory (see
+# provider-catalog.js module header).
+if [[ -z "$VOICE" ]]; then
+  if [[ -f "$SCRIPT_DIR/provider-catalog.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/provider-catalog.sh" 2>/dev/null || true
+  fi
+  if type catalog_default_voice >/dev/null 2>&1; then
+    VOICE="$(catalog_default_voice piper)"
+  else
+    VOICE="en_US-lessac-medium"  # legacy fallback
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # Get SSH connection details from config
 # Prefer ~/.agentvibes/transport-config.json, fall back to legacy host file
@@ -38,10 +57,10 @@ SSH_KEY=""
 SSH_PORT=""
 
 _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
-if [[ -f "$_TRANSPORT_CFG" ]] && command -v python3 &>/dev/null; then
-  SSH_HOST=$(python3 -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('host',''))" 2>/dev/null || echo "")
-  SSH_KEY=$(python3  -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
-  SSH_PORT=$(python3 -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('port',''))" 2>/dev/null || echo "")
+if [[ -f "$_TRANSPORT_CFG" ]] && [[ -n "$PYTHON_BIN" ]]; then
+  SSH_HOST=$("$PYTHON_BIN" -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('host',''))" 2>/dev/null || echo "")
+  SSH_KEY=$("$PYTHON_BIN"  -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
+  SSH_PORT=$("$PYTHON_BIN" -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('agentvibes-receiver',{}); print(p.get('port',''))" 2>/dev/null || echo "")
 fi
 
 if [[ -z "$SSH_HOST" ]]; then