feat: add Timmy Gemma4 Mac wiring helper (#543)

docs/LOCAL_HARDWARE_MCP.md

@@ -1,144 +0,0 @@
-# Local Hardware MCP Integration
-
-Integrate the Model Context Protocol (MCP) to allow Timmy agents to control local hardware securely: file system, smart home (Hue lights), and system information.
-
-## Components
-
-- **MCP Server**: `scripts/hardware_mcp_server.py` — stdio-based MCP server exposing 8 tools
-- **Config Template**: `timmy-local/hardware_mcp_config.yaml` — runtime tuning
-- **Smoke Tests**: `tests/test_hardware_mcp_server.py`
-
-## Prerequisites
-
-```bash
-# MCP SDK
-pip install mcp
-
-# OpenHue CLI (for smart home control)
-brew install openhue/cli/openhue   # macOS
-# or see: https://github.com/openhue/openhue-cli
-
-# Optional: psutil for detailed system_info
-pip install psutil
-```
-
-## Quick Start
-
-### 1. Start the MCP server
-
-The server runs as a subprocess launched by Hermes Agent via the native-MCP integration.
-
-Add to `~/.hermes/config.yaml`:
-
-```yaml
-mcp_servers:
-  hardware:
-    command: "python"
-    args: ["/full/path/to/timmy-home/scripts/hardware_mcp_server.py"]
-    # Optional: add env vars if needed
-    # env:
-    #   OPENHUE_BRIDGE_IP: "192.168.1.100"
-```
-
-### 2. Restart Hermes
-
-On startup, Hermes will:
-1. Launch the hardware MCP server
-2. Discover all 8 tools
-3. Register them with `hardware_*` prefixes (e.g., `hardware_file_read`, `hardware_light_control`)
-
-### 3. Use in conversation
-
-```
-User: Read my Timmy report file.
-Agent: [calls hardware_file_read with path="~/LOCAL_Timmy_REPORT.md"]
-
-User: Turn off the bedroom lights.
-Agent: [calls hardware_light_control with name="Bedroom Lamp", on=false]
-
-User: List files in my downloads folder.
-Agent: [calls hardware_file_list with directory="~/Downloads"]
-
-User: What's my system status?
-Agent: [calls hardware_system_info]
-```
-
-## Tool Reference
-
-| Tool | Purpose | Parameters |
-|------|---------|------------|
-| `hardware_file_read` | Read file (≤10 MB) from home/tmp | `path` (string) |
-| `hardware_file_write` | Write text file | `path`, `content` |
-| `hardware_file_list` | List directory contents | `directory` (default: ~) |
-| `hardware_light_list` | List all Hue lights/rooms/scenes | none |
-| `hardware_light_control` | Control individual light | `name`, `on`, `brightness`, `color`, `temperature` |
-| `hardware_room_control` | Control all lights in a room | `name`, `on`, `brightness` |
-| `hardware_scene_set` | Activate Hue scene | `scene`, `room` |
-| `hardware_system_info` | System info (OS, CPU, memory, disk) | none |
-
-## Security Model
-
-- **File path allowlist**: Only paths under `~` (home), `/tmp`, and `/private/tmp` are permitted.
-- **File size cap**: 10 MB max per read.
-- **No arbitrary commands**: Only explicit tool operations; no shell execution.
-- **Smart home requires OpenHue CLI**: Light control goes through the official Hue CLI which handles bridge authentication.
-- **Graceful degradation**: If `psutil` is missing, `system_info` returns basic platform data; if `openhue` is missing, light tools return install instructions.
-
-## Runtime Configuration
-
-Edit `~/.timmy/hardware/hardware_mcp_config.yaml` (copy from `timmy-local/hardware_mcp_config.yaml`) to adjust:
-
-```yaml
-guards:
-  max_consecutive_errors: 3
-  max_mcp_calls_per_session: 0  # 0 = unlimited
-allowed_dirs:
-  - "~"
-  - "/tmp"
-  - "/private/tmp"
-max_file_size_bytes: 10485760  # 10 MB
-```
-
-## Testing
-
-```bash
-# Validate Python syntax
-python3 -m py_compile scripts/hardware_mcp_server.py
-
-# Run smoke tests
-pytest tests/test_hardware_mcp_server.py -v
-```
-
-## Troubleshooting
-
-**MCP tools not appearing in Hermes**
-
-- Verify `mcp` Python package is installed: `pip show mcp`
-- Check `~/.hermes/config.yaml` syntax (YAML parse)
-- Restart Hermes (MCP connects at startup only)
-- Check Hermes logs: `~/.hermes/logs/` for MCP connection errors
-
-**"openhue CLI not found"**
-
-- Install OpenHue: `brew install openhue/cli/openhue`
-- First run requires pressing the Hue Bridge button to pair
-- Ensure bridge is on same local network
-
-**"Path not allowed"**
-
-- Only home (`~`), `/tmp`, and `/private/tmp` are accessible
-- Use absolute paths or `~/` expansion; relative paths are resolved from home
-
-**File too large**
-
-- Max read size is 10 MB. Split or compress large files.
-
-## Dependencies
-
-| Package | Purpose | Install |
-|---------|---------|---------|
-| `mcp` | MCP SDK (server framework) | `pip install mcp` |
-| `openhue` | Hue light control CLI | `brew install openhue/cli/openhue` |
-| `psutil` (optional) | Detailed memory/disk metrics | `pip install psutil` |
-
-## Closes #466

scripts/README_big_brain.md

@@ -62,6 +62,24 @@ Writes:
 
 ## Usage
 
+### Timmy Mac wiring helper
+
+Use the dedicated Timmy helper when you want to wire a real RunPod or Vertex-style endpoint into the local Mac Hermes config:
+
+```bash
+python3 scripts/timmy_gemma4_mac.py --base-url https://your-openai-bridge.example/v1 --write-config
+python3 scripts/timmy_gemma4_mac.py --vertex-base-url https://your-vertex-bridge.example --write-config
+python3 scripts/timmy_gemma4_mac.py --pod-id <runpod-id> --write-config --verify-chat
+```
+
+The helper writes to `~/.hermes/config.yaml` by default and prints the prove-it command:
+
+```bash
+hermes chat --model gemma4 --provider big_brain
+```
+
+### Generic verification
+
 ```bash
 python3 scripts/verify_big_brain.py
 python3 scripts/big_brain_manager.py

scripts/hardware_mcp_integration.py

@@ -1,56 +0,0 @@
-#!/usr/bin/env python3
-"""Local Hardware MCP operator helper — generate config snippets and verify environment."""
-
-import os
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-HERMES_CONFIG = Path.home() / ".hermes" / "config.yaml"
-HARDWARE_MCP_CONFIG = Path.home() / ".timmy" / "hardware" / "hardware_mcp_config.yaml"
-HARDWARE_SERVER = REPO_ROOT / "scripts" / "hardware_mcp_server.py"
-
-
-def build_mcp_config_snippet() -> str:
-    """Return the mcp_servers YAML snippet for ~/.hermes/config.yaml."""
-    return f"""mcp_servers:
-  hardware:
-    command: "python"
-    args: ["{HARDWARE_SERVER}"]
-"""
-
-
-def build_wakeup_hook() -> str:
-    """Return a bash snippet that can be sourced before Hermes starts (optional)."""
-    return f"""#!/usr/bin/env bash
-# Hardware MCP environment check
-if command -v openhue >/dev/null 2>&1; then
-  echo "[Hardware MCP] OpenHue found: $(openhue version)"
-else
-  echo "[Hardware MCP] Warning: openhue CLI not installed — light control disabled"
-fi
-"""
-
-
-def main():
-    import argparse
-    p = argparse.ArgumentParser(description="Hardware MCP integration helper")
-    p.add_argument("--print-config", action="store_true", help="Print mcp_servers YAML snippet")
-    p.add_argument("--print-hook", action="store_true", help="Print optional session-start hook")
-    p.add_argument("--verify", action="store_true", help="Verify server script exists and is executable")
-    args = p.parse_args()
-
-    if args.print_config:
-        print(build_mcp_config_snippet())
-    elif args.print_hook:
-        print(build_wakeup_hook())
-    elif args.verify:
-        ok = HARDWARE_SERVER.exists()
-        print(f"Server script: {'OK' if ok else 'MISSING'} at {HARDWARE_SERVER}")
-        sys.exit(0 if ok else 1)
-    else:
-        p.print_help()
-
-
-if __name__ == "__main__":
-    main()

scripts/hardware_mcp_server.py

@@ -1,206 +0,0 @@
-#!/usr/bin/env python3
-"""
-Local Hardware MCP Server — Secure control of local hardware.
-
-Exposes tools for:
-  - File system operations (read, write, list) within allowed directories
-  - Smart home control via OpenHue (Philips Hue lights)
-  - System information (safe, read-only)
-
-Security: Enforces directory allowlist for file access.
-"""
-
-import json
-import os
-import subprocess
-import tempfile
-import sys
-from pathlib import Path
-from typing import Any
-
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from mcp.types import Tool, TextContent
-
-ALLOWED_DIRS = [
-    str(Path.home()),          # User home directory
-    "/tmp",                    # macOS symlink to /private/tmp
-    "/private/tmp",            # real tmp path
-    str(Path(tempfile.gettempdir())),  # actual system temp dir
-]
-OPENHUE_CMD = "openhue"
-MAX_FILE_SIZE = 10 * 1024 * 1024
-app = Server("hardware")
-
-
-def is_path_allowed(path: Path) -> bool:
-    try:
-        resolved = path.resolve()
-        return any(resolved.is_relative_to(Path(d).resolve()) for d in ALLOWED_DIRS)
-    except (ValueError, OSError):
-        return False
-
-
-def run_openhue(args: list[str]) -> dict[str, Any]:
-    try:
-        result = subprocess.run([OPENHUE_CMD] + args, capture_output=True, text=True, timeout=30)
-        return {
-            "success": result.returncode == 0,
-            "stdout": result.stdout.strip(),
-            "stderr": result.stderr.strip(),
-            "returncode": result.returncode,
-        }
-    except FileNotFoundError:
-        return {"success": False,
-                "error": "openhue CLI not found. Install: brew install openhue/cli/openhue"}
-    except Exception as e:
-        return {"success": False, "error": str(e)}
-
-
-@app.list_tools()
-async def list_tools():
-    return [
-        Tool(name="file_read",
-             description="Read a file from allowed directories (home, /tmp) up to 10 MB.",
-             inputSchema={"type": "object", "properties": {"path": {"type": "string",
-                          "description": "File path to read (e.g., ~/notes.txt)"}}, "required": ["path"]}),
-        Tool(name="file_write",
-             description="Write text content to a file within allowed directories.",
-             inputSchema={"type": "object", "properties": {"path": {"type": "string"},
-                          "content": {"type": "string"}}, "required": ["path", "content"]}),
-        Tool(name="file_list",
-             description="List files and directories in a given folder.",
-             inputSchema={"type": "object", "properties": {"directory": {"type": "string", "default": "~"}}, "required": []}),
-        Tool(name="light_list",
-             description="List all Hue lights, rooms, and scenes.",
-             inputSchema={"type": "object", "properties": {}, "required": []}),
-        Tool(name="light_control",
-             description="Control a Hue light: on/off, brightness 0-100, color name/hex, temperature 153-500 mirek.",
-             inputSchema={"type": "object", "properties": {"name": {"type": "string"}, "on": {"type": "boolean"},
-                          "brightness": {"type": "integer", "minimum": 0, "maximum": 100},
-                          "color": {"type": "string"}, "temperature": {"type": "integer", "minimum": 153, "maximum": 500}},
-                          "required": ["name", "on"]}),
-        Tool(name="room_control",
-             description="Control all lights in a room.",
-             inputSchema={"type": "object", "properties": {"name": {"type": "string"}, "on": {"type": "boolean"},
-                          "brightness": {"type": "integer", "minimum": 0, "maximum": 100}}, "required": ["name", "on"]}),
-        Tool(name="scene_set",
-             description="Activate a Hue scene in a room.",
-             inputSchema={"type": "object", "properties": {"scene": {"type": "string"}, "room": {"type": "string"}}, "required": ["scene", "room"]}),
-        Tool(name="system_info",
-             description="Get safe system info: OS, CPU count, memory, disk usage.",
-             inputSchema={"type": "object", "properties": {}, "required": []}),
-    ]
-
-
-@app.call_tool()
-async def call_tool(name: str, arguments: dict):
-    if name == "file_read":
-        path = Path(arguments["path"].strip()).expanduser()
-        if not is_path_allowed(path):
-            return [TextContent(type="text", text=json.dumps({"error": f"Path not allowed: {path}"}))]
-        if not path.is_file():
-            return [TextContent(type="text", text=json.dumps({"error": f"File not found: {path}"}))]
-        try:
-            size = path.stat().st_size
-            if size > MAX_FILE_SIZE:
-                return [TextContent(type="text", text=json.dumps({"error": f"File too large: {size} bytes"}))]
-            content = path.read_text()
-            return [TextContent(type="text", text=json.dumps({"path": str(path), "size": size, "content": content}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "file_write":
-        path = Path(arguments["path"].strip()).expanduser()
-        if not is_path_allowed(path):
-            return [TextContent(type="text", text=json.dumps({"error": f"Path not allowed: {path}"}))]
-        try:
-            path.parent.mkdir(parents=True, exist_ok=True)
-            path.write_text(arguments["content"])
-            return [TextContent(type="text", text=json.dumps({"success": True, "path": str(path)}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "file_list":
-        directory = Path(arguments.get("directory", "~").strip()).expanduser()
-        if not is_path_allowed(directory):
-            return [TextContent(type="text", text=json.dumps({"error": f"Directory not allowed: {directory}"}))]
-        if not directory.is_dir():
-            return [TextContent(type="text", text=json.dumps({"error": f"Not a directory: {directory}"}))]
-        try:
-            entries = []
-            for entry in sorted(directory.iterdir()):
-                try:
-                    stat = entry.stat()
-                    entries.append({"name": entry.name, "is_dir": entry.is_dir(),
-                                    "size": stat.st_size if entry.is_file() else None})
-                except (OSError, PermissionError):
-                    pass
-            return [TextContent(type="text", text=json.dumps({"directory": str(directory), "entries": entries, "count": len(entries)}))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    elif name == "light_list":
-        r = run_openhue(["get", "light"])
-        return [TextContent(type="text", text=json.dumps(r))]
-
-    elif name == "light_control":
-        args = ["set", "light", f'"{arguments["name"]}"']
-        if arguments.get("on") is not None:
-            args.append("--on" if arguments["on"] else "--off")
-        if brightness := arguments.get("brightness"):
-            args.append(f"--brightness {brightness}")
-        if color := arguments.get("color"):
-            args.append(f"--color {color}")
-        if temperature := arguments.get("temperature"):
-            args.append(f"--temperature {temperature}")
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "room_control":
-        args = ["set", "room", f'"{arguments["name"]}"']
-        if arguments.get("on") is not None:
-            args.append("--on" if arguments["on"] else "--off")
-        if brightness := arguments.get("brightness"):
-            args.append(f"--brightness {brightness}")
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "scene_set":
-        args = ["set", "scene", arguments["scene"], "--room", arguments["room"]]
-        return [TextContent(type="text", text=json.dumps(run_openhue(args)))]
-
-    elif name == "system_info":
-        try:
-            import platform
-            info = {"platform": platform.system(), "release": platform.release(),
-                    "arch": platform.machine(), "hostname": platform.node(),
-                    "cpu_count": os.cpu_count()}
-            try:
-                import psutil
-                mem = psutil.virtual_memory()
-                info["memory_gb"] = round(mem.total / (1024**3), 2)
-                disk = psutil.disk_usage(str(Path.home()))
-                info["disk_home_gb"] = round(disk.total / (1024**3), 2)
-            except ImportError:
-                info["memory_gb"] = "psutil not installed"
-                info["disk_home_gb"] = "psutil not installed"
-            return [TextContent(type="text", text=json.dumps(info, indent=2))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({"error": str(e)}))]
-
-    else:
-        return [TextContent(type="text", text=json.dumps({
-            "error": f"Unknown tool: {name}",
-            "available": ["file_read", "file_write", "file_list", "light_list",
-                         "light_control", "room_control", "scene_set", "system_info"],
-        }))]
-
-
-async def main():
-    async with stdio_server() as (rs, ws):
-        await app.run(rs, ws, app.create_initialization_options())
-
-
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())
-

scripts/timmy_gemma4_mac.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Timmy Mac Gemma 4 wiring helper for RunPod / Vertex-style Big Brain providers.
+
+Refs: timmy-home #543
+
+Safe by default:
+- computes a Big Brain base URL from an explicit URL, Vertex bridge URL, or RunPod pod id
+- can provision a RunPod pod when --apply-runpod is used and a token is available
+- can write the resolved endpoint into a Hermes config when --write-config is used
+- can verify an OpenAI-compatible chat endpoint when --verify-chat is used
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+from urllib import request
+
+from scripts.bezalel_gemma4_vps import (
+    DEFAULT_CLOUD_TYPE,
+    DEFAULT_GPU_TYPE,
+    DEFAULT_MODEL,
+    DEFAULT_PROVIDER_NAME,
+    build_runpod_endpoint,
+    deploy_runpod,
+    update_config_text,
+)
+
+DEFAULT_TOKEN_FILE = Path.home() / ".config" / "runpod" / "access_key"
+DEFAULT_CONFIG_PATH = Path.home() / ".hermes" / "config.yaml"
+
+
+def _normalize_openai_base(base_url: str | None) -> str:
+    if not base_url:
+        return ""
+    cleaned = str(base_url).strip().rstrip("/")
+    return cleaned if cleaned.endswith("/v1") else f"{cleaned}/v1"
+
+
+def choose_base_url(*, vertex_base_url: str | None = None, base_url: str | None = None, pod_id: str | None = None) -> str:
+    if vertex_base_url:
+        return _normalize_openai_base(vertex_base_url)
+    if base_url:
+        return _normalize_openai_base(base_url)
+    if pod_id:
+        return build_runpod_endpoint(pod_id)
+    return "https://YOUR_BIG_BRAIN_HOST/v1"
+
+
+def write_config_file(config_path: Path, *, base_url: str, model: str = DEFAULT_MODEL, provider_name: str = DEFAULT_PROVIDER_NAME) -> str:
+    original = config_path.read_text() if config_path.exists() else ""
+    updated = update_config_text(original, base_url=base_url, model=model, provider_name=provider_name)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(updated)
+    return updated
+
+
+def verify_openai_chat(base_url: str, *, model: str = DEFAULT_MODEL, prompt: str = "Say READY") -> str:
+    payload = json.dumps(
+        {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+            "max_tokens": 16,
+        }
+    ).encode()
+    req = request.Request(
+        f"{base_url.rstrip('/')}/chat/completions",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode())
+    return data["choices"][0]["message"]["content"]
+
+
+def build_summary(*, base_url: str, model: str, provider_name: str = DEFAULT_PROVIDER_NAME, config_path: Path = DEFAULT_CONFIG_PATH) -> dict[str, Any]:
+    return {
+        "provider_name": provider_name,
+        "base_url": base_url,
+        "model": model,
+        "config_path": str(config_path),
+        "verification_commands": [
+            "python3 scripts/verify_big_brain.py",
+            f"python3 scripts/timmy_gemma4_mac.py --base-url {base_url} --write-config --verify-chat",
+            "hermes chat --model gemma4 --provider big_brain",
+        ],
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Wire a RunPod/Vertex Gemma 4 endpoint into Timmy's Mac Hermes config.")
+    parser.add_argument("--pod-name", default="timmy-gemma4")
+    parser.add_argument("--gpu-type", default=DEFAULT_GPU_TYPE)
+    parser.add_argument("--cloud-type", default=DEFAULT_CLOUD_TYPE)
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--provider-name", default=DEFAULT_PROVIDER_NAME)
+    parser.add_argument("--token-file", type=Path, default=DEFAULT_TOKEN_FILE)
+    parser.add_argument("--config-path", type=Path, default=DEFAULT_CONFIG_PATH)
+    parser.add_argument("--pod-id", help="Existing RunPod pod id to convert into an OpenAI-compatible base URL")
+    parser.add_argument("--base-url", help="Explicit OpenAI-compatible base URL")
+    parser.add_argument("--vertex-base-url", help="Vertex AI OpenAI-compatible bridge base URL")
+    parser.add_argument("--apply-runpod", action="store_true", help="Provision a RunPod pod using the RunPod GraphQL API")
+    parser.add_argument("--write-config", action="store_true", help="Write the resolved endpoint into --config-path")
+    parser.add_argument("--verify-chat", action="store_true", help="Run a lightweight OpenAI-compatible chat probe")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    summary: dict[str, Any] = {
+        "pod_name": args.pod_name,
+        "gpu_type": args.gpu_type,
+        "cloud_type": args.cloud_type,
+        "model": args.model,
+        "provider_name": args.provider_name,
+        "actions": [],
+    }
+
+    base_url = choose_base_url(vertex_base_url=args.vertex_base_url, base_url=args.base_url, pod_id=args.pod_id)
+
+    if args.apply_runpod:
+        if not args.token_file.exists():
+            raise SystemExit(f"RunPod token file not found: {args.token_file}")
+        api_key = args.token_file.read_text().strip()
+        deployed = deploy_runpod(api_key=api_key, name=args.pod_name, gpu_type=args.gpu_type, cloud_type=args.cloud_type, model=args.model)
+        summary["deployment"] = deployed
+        base_url = deployed["base_url"]
+        summary["actions"].append("deployed_runpod_pod")
+
+    summary.update(build_summary(base_url=base_url, model=args.model, provider_name=args.provider_name, config_path=args.config_path))
+
+    if args.write_config:
+        write_config_file(args.config_path, base_url=base_url, model=args.model, provider_name=args.provider_name)
+        summary["actions"].append("wrote_config")
+
+    if args.verify_chat:
+        summary["verify_response"] = verify_openai_chat(base_url, model=args.model)
+        summary["actions"].append("verified_chat")
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+        return
+
+    print("--- Timmy Gemma4 Mac Wiring ---")
+    print(f"Provider: {args.provider_name}")
+    print(f"Base URL: {base_url}")
+    print(f"Model: {args.model}")
+    print(f"Config path: {args.config_path}")
+    if "verify_response" in summary:
+        print(f"Verify response: {summary['verify_response']}")
+    if summary["actions"]:
+        print("Actions: " + ", ".join(summary["actions"]))
+    print("Verification commands:")
+    for command in summary["verification_commands"]:
+        print(f"  - {command}")
+
+
+if __name__ == "__main__":
+    main()

tests/test_hardware_mcp_functional.py

@@ -1,51 +0,0 @@
-#!/usr/bin/env python3
-"""Functional test for hardware_mcp_server — uses asyncio.get_event_loop for restricted envs."""
-
-import asyncio, json, tempfile, sys
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-from scripts.hardware_mcp_server import call_tool, is_path_allowed
-
-async def run_tests():
-    # Path allowlist
-    assert is_path_allowed(Path.home() / "any.txt")
-    assert is_path_allowed(Path("/tmp/foo"))
-    assert not is_path_allowed(Path("/etc/passwd"))
-    print("✓ Path allowlist")
-
-    # file_list on home
-    res = await call_tool("file_list", {"directory": "~"})
-    data = json.loads(res[0].text)
-    assert "entries" in data and data["count"] >= 0
-    print(f"✓ file_list works, entries: {data['count']}")
-
-    # file_write + file_read round-trip in temp dir
-    with tempfile.TemporaryDirectory() as td:
-        fp = Path(td) / "hmcp_test.txt"
-        content = "Hardware MCP round-trip OK"
-        w = await call_tool("file_write", {"path": str(fp), "content": content})
-        assert json.loads(w[0].text).get("success")
-        r = await call_tool("file_read", {"path": str(fp)})
-        assert json.loads(r[0].text)["content"] == content
-    print("✓ file write/read round-trip")
-
-    # file_read error: missing file
-    err = await call_tool("file_read", {"path": str(Path.home() / "no_such_file_xyz")})
-    assert "error" in json.loads(err[0].text)
-    print("✓ file_read reports missing file")
-
-    # Security: path traversal blocked
-    block = await call_tool("file_read", {"path": "/etc/passwd"})
-    bd = json.loads(block[0].text)
-    assert "not allowed" in bd.get("error", "").lower()
-    print("✓ Path traversal blocked")
-
-    print("\nAll functional checks passed!")
-
-if __name__ == "__main__":
-    # Use get_event_loop for environments where asyncio.run is disabled
-    try:
-        asyncio.run(run_tests())
-    except RuntimeError:
-        loop = asyncio.get_event_loop()
-        loop.run_until_complete(run_tests())

tests/test_hardware_mcp_server.py

@@ -1,126 +0,0 @@
-#!/usr/bin/env python3
-"""Smoke tests for hardware_mcp_server."""
-
-import json
-import os
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-from unittest import TestCase
-
-# Add repo root to path
-ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(ROOT))
-
-
-class TestHardwareMCPToolDefinitions(TestCase):
-    """Verify the MCP server is well-formed and tools have required schemas."""
-
-    def test_server_imports(self):
-        """Server module must import cleanly."""
-        import importlib.util
-        spec = importlib.util.spec_from_file_location(
-            "hardware_mcp_server",
-            ROOT / "scripts" / "hardware_mcp_server.py"
-        )
-        self.assertIsNotNone(spec)
-        mod = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(mod)
-        self.assertTrue(hasattr(mod, "app"))
-        self.assertTrue(hasattr(mod, "list_tools"))
-        self.assertTrue(hasattr(mod, "call_tool"))
-
-    def test_list_tools_returns_at_least_five_tools(self):
-        """list_tools() must return multiple tools covering file ops, lights, and system info."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        tool_names = [t.name for t in tools]
-        # Core capabilities
-        self.assertIn("file_read", tool_names)
-        self.assertIn("file_write", tool_names)
-        self.assertIn("file_list", tool_names)
-        self.assertIn("light_list", tool_names)
-        self.assertIn("light_control", tool_names)
-        self.assertIn("room_control", tool_names)
-        self.assertIn("scene_set", tool_names)
-        self.assertIn("system_info", tool_names)
-        self.assertGreaterEqual(len(tools), 8)
-
-    def test_file_read_schema_requires_path(self):
-        """file_read tool must require 'path' parameter."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "file_read")
-        self.assertIn("path", ft.inputSchema["properties"])
-        self.assertIn("path", ft.inputSchema["required"])
-
-    def test_light_control_schema_requires_name_and_on(self):
-        """light_control requires name and on."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "light_control")
-        self.assertIn("name", ft.inputSchema["required"])
-        self.assertIn("on", ft.inputSchema["required"])
-
-    def test_system_info_is_readonly(self):
-        """system_info tool takes no arguments."""
-        import asyncio
-        from scripts.hardware_mcp_server import list_tools
-        tools = asyncio.run(list_tools())
-        ft = next(t for t in tools if t.name == "system_info")
-        self.assertEqual(ft.inputSchema.get("required", []), [])
-        self.assertEqual(len(ft.inputSchema.get("properties", {})), 0)
-
-    def test_file_write_path_allowed_check(self):
-        """File write must enforce path allowlist (regression guard)."""
-        from scripts.hardware_mcp_server import is_path_allowed, Path
-        self.assertTrue(is_path_allowed(Path.home() / "test.txt"))
-        self.assertTrue(is_path_allowed(Path("/tmp/test.txt")))
-        # Outside allowed dirs should be rejected
-        self.assertFalse(is_path_allowed(Path("/etc/passwd")))
-
-    def test_run_openhue_error_handling(self):
-        """openhue runner returns structured error when CLI missing."""
-        from scripts.hardware_mcp_server import run_openhue
-        result = run_openhue(["get", "light"])
-        # On a system without openhue, must return success=False with helpful error
-        self.assertIn("success", result)
-        if not result.get("success"):
-            self.assertIn("error", result)
-            self.assertIn("openhue", result.get("error", "").lower())
-
-
-class TestHardwareMCPConfigCompleteness(TestCase):
-    """Validate config template matches tool set."""
-
-    def test_config_template_exists(self):
-        self.assertTrue((ROOT / "timmy-local" / "hardware_mcp_config.yaml").exists())
-
-    def test_config_lists_all_tools(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        # All tool names should appear in the tools: section
-        for tool in ["file_read", "file_write", "file_list", "light_list",
-                     "light_control", "room_control", "scene_set", "system_info"]:
-            self.assertIn(tool, content, f"Tool {tool} missing from config tools list")
-
-    def test_config_has_security_guards(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        self.assertIn("max_consecutive_errors", content)
-        self.assertIn("allowed_dirs", content)
-        self.assertIn("max_file_size_bytes", content)
-
-    def test_config_has_server_key(self):
-        with open(ROOT / "timmy-local" / "hardware_mcp_config.yaml") as f:
-            content = f.read()
-        self.assertIn("server_key: hardware", content)
-
-
-if __name__ == "__main__":
-    import unittest
-    unittest.main()

tests/test_timmy_gemma4_mac.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = ROOT / "scripts" / "timmy_gemma4_mac.py"
+README = ROOT / "scripts" / "README_big_brain.md"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("timmy_gemma4_mac", str(SCRIPT))
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["timmy_gemma4_mac"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class _FakeResponse:
+    def __init__(self, payload: dict):
+        self._payload = json.dumps(payload).encode()
+
+    def read(self) -> bytes:
+        return self._payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+def test_script_exists() -> None:
+    assert SCRIPT.exists(), "scripts/timmy_gemma4_mac.py must exist"
+
+
+def test_default_paths_target_timmy_mac_hermes() -> None:
+    mod = load_module()
+    assert mod.DEFAULT_CONFIG_PATH == Path.home() / ".hermes" / "config.yaml"
+    assert mod.DEFAULT_TOKEN_FILE == Path.home() / ".config" / "runpod" / "access_key"
+
+
+def test_choose_base_url_prefers_vertex_then_explicit_then_runpod() -> None:
+    mod = load_module()
+    assert mod.choose_base_url(vertex_base_url="https://vertex-proxy.example/v1") == "https://vertex-proxy.example/v1"
+    assert mod.choose_base_url(base_url="https://custom-endpoint/v1") == "https://custom-endpoint/v1"
+    assert mod.choose_base_url(pod_id="abc123") == "https://abc123-11434.proxy.runpod.net/v1"
+
+
+def test_build_summary_includes_prove_it_commands() -> None:
+    mod = load_module()
+    summary = mod.build_summary(base_url="https://vertex-proxy.example/v1", model="gemma4:latest")
+    assert summary["verification_commands"][0] == "python3 scripts/verify_big_brain.py"
+    assert any("hermes chat --model gemma4 --provider big_brain" in cmd for cmd in summary["verification_commands"])
+
+
+def test_verify_openai_chat_targets_chat_completions() -> None:
+    mod = load_module()
+    response_payload = {
+        "choices": [{"message": {"content": "READY"}}]
+    }
+
+    with patch("timmy_gemma4_mac.request.urlopen", return_value=_FakeResponse(response_payload)) as mocked:
+        result = mod.verify_openai_chat("https://vertex-proxy.example/v1", model="gemma4:latest", prompt="say READY")
+
+    assert result == "READY"
+    req = mocked.call_args.args[0]
+    assert req.full_url == "https://vertex-proxy.example/v1/chat/completions"
+
+
+def test_readme_mentions_timmy_mac_wiring_flow() -> None:
+    text = README.read_text(encoding="utf-8")
+    required = [
+        "scripts/timmy_gemma4_mac.py",
+        "--vertex-base-url",
+        "--write-config",
+        "python3 scripts/verify_big_brain.py",
+        "hermes chat --model gemma4 --provider big_brain",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing

timmy-local/hardware/README.md

@@ -1,3 +0,0 @@
-# hardware MCP config
-
-Copy `hardware_mcp_config.yaml` to `~/.timmy/hardware/hardware_mcp_config.yaml` to enable runtime tuning.

timmy-local/hardware_mcp_config.yaml

@@ -1,67 +0,0 @@
-# ═══════════════════════════════════════════════════════════════════════
-# Local Hardware MCP — Runtime Configuration
-# ═══════════════════════════════════════════════════════════════════════
-# Edit this file to tune hardware control settings.
-# Hermes loads this at session start when the hardware MCP server is enabled.
-#
-# Location: ~/.timmy/hardware/hardware_mcp_config.yaml
-# ═══════════════════════════════════════════════════════════════════════
-
-# ── Server Identity ───────────────────────────────────────────────────
-server_key: hardware
-
-# ── Tool Names ────────────────────────────────────────────────────────
-# Exact tool names Hermes registers.  Update if you rename tools in
-# hardware_mcp_server.py.
-tools:
-  - name: file_read
-    hint: "Read a file from an allowed directory (home, /tmp). Max 10 MB."
-  - name: file_write
-    hint: "Write text content to a file within allowed directories."
-  - name: file_list
-    hint: "List files and directories in a given folder."
-  - name: light_list
-    hint: "List all Hue lights, rooms, and scenes from OpenHue."
-  - name: light_control
-    hint: "Control a specific Hue light: on/off, brightness, color, temperature."
-  - name: room_control
-    hint: "Control all lights in a room: on/off, brightness."
-  - name: scene_set
-    hint: "Activate a Hue scene in a room."
-  - name: system_info
-    hint: "Get safe system information: OS, CPU count, memory usage, disk space."
-
-# ── Security Guards ───────────────────────────────────────────────────
-guards:
-  # Maximum consecutive tool errors before stopping.
-  max_consecutive_errors: 3
-
-  # Max total hardware MCP calls per session (0 = unlimited).
-  max_mcp_calls_per_session: 0
-
-  # Allowed directories for file operations (expanded paths).
-  allowed_dirs:
-    - "~"
-    - "/tmp"
-    - "/private/tmp"
-
-  # Maximum file size for reads (bytes).
-  max_file_size_bytes: 10485760  # 10 MB
-
-# ── OpenHue ───────────────────────────────────────────────────────────
-# Path to openhue CLI (auto-detected if in PATH).
-openhue_command: "openhue"
-
-# ── Dependencies ───────────────────────────────────────────────────────
-# Prerequisites:
-#   - OpenHue CLI: brew install openhue/cli/openhue (macOS) or see https://github.com/openhue/openhue-cli
-#   - MCP SDK: pip install mcp
-#   - For system_info: pip install psutil (optional, for detailed memory/disk metrics)
-#
-# Config in ~/.hermes/config.yaml:
-#   mcp_servers:
-#     hardware:
-#       command: "python"
-#       args: ["/Users/you/path/to/timmy-home/scripts/hardware_mcp_server.py"]
-#       env:
-#         OPENHUE_BRIDGE_IP: "192.168.1.xx"  # optional, if openhue needs it