agenticros 0.0.1 → 0.1.0

package/runtime/scripts/setup_workspace.sh

@@ -0,0 +1,484 @@
+#!/bin/bash
+# setup_workspace.sh - Cross-platform setup for AgenticROS development environment
+#
+# DESCRIPTION:
+#   This script performs the initial setup required for AgenticROS development.
+#   It supports both Ubuntu (native ROS2) and macOS (RoboStack with mamba).
+#   The script installs dependencies, creates the appropriate environment,
+#   and builds all ROS2 packages. Run this script once before using the
+#   activate_workspace.sh script for daily development.
+#
+# USAGE:
+#   ./scripts/setup_workspace.sh [options]
+#
+# OPTIONS:
+#   -e, --env-name NAME     Name of the environment to create (default: ros_env)
+#   -d, --ros-distro DISTRO ROS2 distribution (default: humble)
+#   -h, --help              Show this help message
+#
+# EXAMPLES:
+#   # Use defaults (ros_env, jazzy)
+#   ./scripts/setup_workspace.sh
+#
+#   # Custom environment name
+#   ./scripts/setup_workspace.sh --env-name my_ros_env
+#
+#   # Different ROS2 distro
+#   ./scripts/setup_workspace.sh --ros-distro humble
+#
+# PLATFORMS SUPPORTED:
+#   - Ubuntu/Debian: Native ROS2 installation with apt + venv
+#   - macOS: RoboStack with mamba/conda environment
+#
+# WHAT IT DOES:
+#   1. Detects platform (Ubuntu vs macOS)
+#   2. Installs platform-specific infrastructure
+#   3. Creates appropriate environment (venv with --system-site-packages vs conda)
+#   4. Installs ROS2, rosbridge_library, and all required development tools
+#   5. Installs agent-specific pip dependencies (aiortc, websockets)
+#   6. Builds all ROS2 packages in ros2_ws
+#   7. Validates the complete setup
+
+set -e  # Exit on any error
+
+# Default values
+DEFAULT_ENV_NAME="ros_env"
+DEFAULT_ROS_DISTRO="humble"
+ENV_NAME=""
+ROS_DISTRO=""
+
+# Find the repository root
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+ROS2_WS_PATH="$REPO_ROOT/ros2_ws"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Logging functions
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Help function
+show_help() {
+    cat << EOF
+AgenticROS Development Environment Setup
+
+USAGE:
+    $0 [options]
+
+OPTIONS:
+    -e, --env-name NAME     Name of the environment to create (default: $DEFAULT_ENV_NAME)
+    -d, --ros-distro DISTRO ROS2 distribution (default: $DEFAULT_ROS_DISTRO)
+    -h, --help              Show this help message
+
+EXAMPLES:
+    # Use defaults
+    $0
+
+    # Custom environment name
+    $0 --env-name my_ros_env
+
+    # Different ROS2 distribution
+    $0 --ros-distro humble
+
+SUPPORTED PLATFORMS:
+    - Ubuntu/Debian: Native ROS2 with apt + Python venv
+    - macOS: RoboStack with mamba/conda environment
+
+SUPPORTED ROS2 DISTRIBUTIONS:
+    - jazzy (default)
+    - humble
+    - kilted
+EOF
+}
+
+# Parse command line arguments
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            -e|--env-name)
+                ENV_NAME="$2"
+                shift 2
+                ;;
+            -d|--ros-distro)
+                ROS_DISTRO="$2"
+                shift 2
+                ;;
+            -h|--help)
+                show_help
+                exit 0
+                ;;
+            *)
+                log_error "Unknown option: $1"
+                show_help
+                exit 1
+                ;;
+        esac
+    done
+
+    # Set defaults if not specified
+    ENV_NAME="${ENV_NAME:-$DEFAULT_ENV_NAME}"
+    ROS_DISTRO="${ROS_DISTRO:-$DEFAULT_ROS_DISTRO}"
+}
+
+# Platform detection
+detect_platform() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        PLATFORM="macos"
+    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        if command -v apt &> /dev/null; then
+            PLATFORM="ubuntu"
+        else
+            log_error "Linux platform detected but apt not found. Only Ubuntu/Debian supported."
+            exit 1
+        fi
+    else
+        log_error "Unsupported platform: $OSTYPE"
+        log_error "Supported platforms: macOS, Ubuntu/Debian"
+        exit 1
+    fi
+}
+
+# Check and install mamba/conda if needed (for macOS)
+check_mamba() {
+    if ! command -v mamba &> /dev/null; then
+        if ! command -v conda &> /dev/null; then
+            log_info "Neither mamba nor conda found. Installing miniforge automatically..."
+
+            local installer="Miniforge3-MacOSX-$(uname -m).sh"
+            local url="https://github.com/conda-forge/miniforge/releases/latest/download/$installer"
+
+            log_info "Downloading miniforge installer..."
+            if ! curl -L -O "$url"; then
+                log_error "Failed to download miniforge installer"
+                exit 1
+            fi
+
+            log_info "Installing miniforge..."
+            if ! bash "$installer" -b -p "$HOME/miniforge3"; then
+                log_error "Failed to install miniforge"
+                exit 1
+            fi
+
+            rm -f "$installer"
+            eval "$($HOME/miniforge3/bin/conda shell.$(basename $SHELL) hook)"
+            log_success "Miniforge installed successfully"
+        else
+            log_warning "conda found but mamba not available. Installing mamba..."
+            conda install mamba -c conda-forge -y
+        fi
+    fi
+}
+
+# Validate ROS2 distribution support
+validate_ros_distro() {
+    local supported_distros=("humble" "jazzy" "kilted")
+    local distro_supported=false
+
+    for supported in "${supported_distros[@]}"; do
+        if [[ "$ROS_DISTRO" == "$supported" ]]; then
+            distro_supported=true
+            break
+        fi
+    done
+
+    if [[ "$distro_supported" == false ]]; then
+        log_error "ROS2 distribution '$ROS_DISTRO' is not supported"
+        log_error "Supported distributions: ${supported_distros[*]}"
+        exit 1
+    fi
+}
+
+# Check if already in conda environment
+check_conda_env_active() {
+    if [[ -n "$CONDA_DEFAULT_ENV" ]]; then
+        log_warning "Already in conda environment: $CONDA_DEFAULT_ENV"
+        if [[ "$CONDA_DEFAULT_ENV" == "$ENV_NAME" ]]; then
+            log_info "Already in target environment '$ENV_NAME', continuing setup..."
+            return 0
+        else
+            log_warning "In different environment. Will deactivate and switch to '$ENV_NAME'"
+            conda deactivate 2>/dev/null || true
+            mamba deactivate 2>/dev/null || true
+        fi
+    fi
+    return 1
+}
+
+# Ubuntu setup function
+setup_ubuntu() {
+    log_info "Setting up Ubuntu environment..."
+
+    # Step 1: Install system dependencies
+    log_info "[1/5] Installing system dependencies..."
+    sudo apt update
+    sudo apt install -y \
+        python3-dev \
+        python3-venv \
+        python3-pip \
+        build-essential \
+        cmake \
+        pkg-config \
+        curl \
+        gnupg2 \
+        lsb-release \
+        software-properties-common
+
+    # Step 2: Install ROS2 and required packages
+    log_info "[2/5] Setting up ROS2 $ROS_DISTRO..."
+
+    if ! command -v ros2 &> /dev/null; then
+        log_info "Installing ROS2 $ROS_DISTRO..."
+
+        sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
+
+        sudo apt update
+    else
+        log_success "ROS2 base already installed"
+    fi
+
+    log_info "Ensuring all required ROS2 packages are installed..."
+    sudo apt install -y \
+        ros-$ROS_DISTRO-ros-base \
+        ros-$ROS_DISTRO-rosbridge-library \
+        ros-$ROS_DISTRO-rosbridge-suite \
+        python3-colcon-common-extensions
+
+    log_success "All required ROS2 packages installed"
+
+    # Step 3: Create Python virtual environment with system site-packages
+    # This is critical: rclpy and rosbridge_library are system-installed via apt.
+    # The venv must inherit them via --system-site-packages.
+    log_info "[3/5] Setting up Python virtual environment..."
+    VENV_PATH="$REPO_ROOT/$ENV_NAME"
+
+    if [ -d "$VENV_PATH" ]; then
+        log_warning "Virtual environment already exists at: $VENV_PATH"
+    else
+        log_info "Creating virtual environment at: $VENV_PATH (with --system-site-packages)"
+        python3 -m venv "$VENV_PATH" --system-site-packages
+        log_success "Virtual environment created"
+    fi
+
+    # Step 4: Install agent-specific Python packages
+    log_info "[4/5] Installing Python packages for agenticros_agent..."
+    source "$VENV_PATH/bin/activate"
+    pip install --upgrade pip
+    pip install aiortc websockets
+    log_success "Python packages installed (aiortc, websockets)"
+
+    # Step 5: Build ROS2 packages
+    log_info "[5/5] Building ROS2 packages..."
+    cd "$ROS2_WS_PATH"
+    source /opt/ros/$ROS_DISTRO/setup.bash
+    colcon build --symlink-install
+    log_success "ROS2 packages built successfully"
+}
+
+# macOS setup function
+setup_macos() {
+    log_info "Setting up macOS environment with RoboStack..."
+
+    # Step 1: Check mamba installation
+    log_info "[1/5] Checking mamba installation..."
+    check_mamba
+    log_success "Mamba is available"
+
+    # Step 2: Create conda environment
+    log_info "[2/5] Setting up conda environment '$ENV_NAME'..."
+
+    local already_in_target_env=false
+    if check_conda_env_active; then
+        already_in_target_env=true
+    fi
+
+    if mamba env list | grep -q "^$ENV_NAME "; then
+        log_warning "Environment '$ENV_NAME' already exists"
+        if [[ "$already_in_target_env" == false ]]; then
+            log_info "Activating existing environment..."
+            eval "$(mamba shell hook)"
+            mamba activate "$ENV_NAME"
+        fi
+    else
+        log_info "Creating new environment '$ENV_NAME'..."
+        mamba create -n "$ENV_NAME" -y
+        eval "$(mamba shell hook)"
+        mamba activate "$ENV_NAME"
+    fi
+
+    conda config --env --add channels conda-forge
+    conda config --env --remove channels defaults 2>/dev/null || true
+    conda config --env --add channels robostack-$ROS_DISTRO
+
+    # Step 3: Install ROS2 and development tools
+    log_info "[3/5] Installing ROS2 $ROS_DISTRO and development tools..."
+    mamba install -y \
+        ros-$ROS_DISTRO-ros-base \
+        ros-$ROS_DISTRO-rosbridge-library \
+        compilers \
+        cmake \
+        pkg-config \
+        make \
+        ninja \
+        colcon-common-extensions \
+        python \
+        pip
+
+    log_success "ROS2 and development tools installed"
+
+    # Step 4: Install agent-specific Python packages
+    log_info "[4/5] Installing Python packages for agenticros_agent..."
+    pip install aiortc websockets
+    log_success "Python packages installed (aiortc, websockets)"
+
+    # Deactivate and reactivate to ensure proper ROS setup
+    mamba deactivate
+    mamba activate "$ENV_NAME"
+
+    # Step 5: Build ROS2 packages
+    log_info "[5/5] Building ROS2 packages..."
+    cd "$ROS2_WS_PATH"
+    colcon build --symlink-install
+    log_success "ROS2 packages built successfully"
+}
+
+# Validation function
+validate_setup() {
+    log_info "Validating setup..."
+
+    cd "$ROS2_WS_PATH"
+
+    if [[ "$PLATFORM" == "macos" ]]; then
+        eval "$(mamba shell hook)"
+        mamba activate "$ENV_NAME"
+    else
+        source /opt/ros/$ROS_DISTRO/setup.bash
+        source "$REPO_ROOT/$ENV_NAME/bin/activate"
+    fi
+
+    # Source workspace
+    if [ -f "install/setup.bash" ]; then
+        source install/setup.bash
+        log_success "Workspace sourced successfully"
+    else
+        log_error "Workspace build failed - install/setup.bash not found"
+        return 1
+    fi
+
+    # Test ROS2 functionality
+    if command -v ros2 &> /dev/null; then
+        log_success "ROS2 command available"
+    else
+        log_error "ROS2 command not available"
+        return 1
+    fi
+
+    # Test if our packages are available
+    local all_found=true
+    for pkg in agenticros_msgs agenticros_discovery agenticros_agent; do
+        if ros2 pkg list 2>/dev/null | grep -q "$pkg"; then
+            log_success "Package found: $pkg"
+        else
+            log_warning "Package not found: $pkg"
+            all_found=false
+        fi
+    done
+
+    # Test agent Python dependencies
+    if python3 -c "import aiortc; import websockets" 2>/dev/null; then
+        log_success "Agent Python dependencies available (aiortc, websockets)"
+    else
+        log_warning "Agent Python dependencies missing (aiortc or websockets)"
+    fi
+
+    # Test rosbridge_library availability
+    if python3 -c "from rosbridge_library.internal.ros_loader import get_message_class" 2>/dev/null; then
+        log_success "rosbridge_library available"
+    else
+        log_warning "rosbridge_library not available"
+    fi
+
+    return 0
+}
+
+# Main execution
+main() {
+    # shellcheck source=scripts/lib/agenticros-banner.sh
+    source "$REPO_ROOT/scripts/lib/agenticros-banner.sh"
+    agenticros_banner
+    echo "AgenticROS Development Setup"
+    echo ""
+
+    parse_args "$@"
+    detect_platform
+
+    if [[ "$PLATFORM" == "macos" ]]; then
+        validate_ros_distro
+    fi
+
+    log_info "Platform detected: $PLATFORM"
+    log_info "Environment name: $ENV_NAME"
+    log_info "ROS2 distribution: $ROS_DISTRO"
+    log_info "Repository root: $REPO_ROOT"
+
+    if [[ "$PLATFORM" == "macos" && -n "$CONDA_DEFAULT_ENV" ]]; then
+        log_info "Current conda environment: $CONDA_DEFAULT_ENV"
+    fi
+    echo ""
+
+    case $PLATFORM in
+        ubuntu)
+            setup_ubuntu
+            ;;
+        macos)
+            setup_macos
+            ;;
+        *)
+            log_error "Unsupported platform: $PLATFORM"
+            exit 1
+            ;;
+    esac
+
+    echo ""
+
+    if validate_setup; then
+        log_success "Setup validation passed!"
+    else
+        log_error "Setup validation failed!"
+        exit 1
+    fi
+
+    echo ""
+    echo "Setup complete!"
+    echo ""
+    echo "Next steps:"
+    echo "  1. Activate your development environment for daily use:"
+    echo "     source $REPO_ROOT/scripts/activate_workspace.sh"
+    echo ""
+    echo "  2. Test discovery node:"
+    echo "     ros2 run agenticros_discovery discovery_node"
+    echo ""
+    echo "  3. Test agent node (requires signaling server):"
+    echo "     AGENTICROS_SIGNALING_URL=ws://localhost:8000 ros2 run agenticros_agent agent_node"
+    echo ""
+}
+
+main "$@"

package/runtime/scripts/smoke_test_nemoclaw.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# Smoke-test the hybrid NemoClaw + AgenticROS bridge.
+#
+# Checks, in order:
+#   1. NemoClaw sandbox container is up.
+#   2. agenticros_rosbridge policy is loaded into the live gateway bundle
+#      with the SSRF allowed_ips block (so host.docker.internal is reachable).
+#   3. rosbridge_server is bound on the host (0.0.0.0:9090).
+#   4. The plugin's actual TCP connection through the OPA proxy is ALLOWED
+#      (not denied by engine:ssrf or engine:opa).
+#   5. A real WebSocket request to /rosapi/topics through the proxy returns
+#      a list of ROS 2 topics (i.e. the gateway can both reach rosbridge and
+#      speak its protocol).
+#   6. The NemoClaw dashboard HTTP endpoint serves a non-empty body.
+#
+# Exit code: 0 on all-pass, 1 on any failure. Prints a one-line PASS/FAIL per
+# check + a final summary.
+#
+# Usage:   ./scripts/smoke_test_nemoclaw.sh
+
+set -uo pipefail
+
+GREEN=$'\033[32m'; RED=$'\033[31m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+PASS=0; FAIL=0
+pass() { echo "${GREEN}PASS${RESET} $*"; PASS=$((PASS+1)); }
+fail() { echo "${RED}FAIL${RESET} $*"; FAIL=$((FAIL+1)); }
+warn() { echo "${YELLOW}WARN${RESET} $*"; }
+
+CONTAINER=$(docker ps --format '{{.Names}}' 2>/dev/null | grep '^openshell-nemo-' | head -1 || true)
+if [[ -z "${CONTAINER}" ]]; then
+  fail "No openshell-nemo-* container running — start NemoClaw with 'nemoclaw nemo start'"
+  exit 1
+fi
+pass "sandbox container: ${CONTAINER}"
+
+# ----- 2. agenticros_rosbridge policy loaded with allowed_ips ---------------
+OPENSHELL_BIN="${OPENSHELL_BIN:-$(command -v openshell || echo "$HOME/.local/bin/openshell")}"
+if [[ ! -x "${OPENSHELL_BIN}" ]]; then
+  warn "openshell CLI not found at ${OPENSHELL_BIN} — skipping policy bundle check"
+else
+  POLICY_BUNDLE=$("${OPENSHELL_BIN}" policy get --full nemo 2>/dev/null || true)
+  if grep -q 'agenticros_rosbridge:' <<<"${POLICY_BUNDLE}"; then
+    if grep -q 'allowed_ips:' <<<"${POLICY_BUNDLE}"; then
+      pass "agenticros_rosbridge policy is loaded with allowed_ips (SSRF guard satisfied)"
+    else
+      fail "agenticros_rosbridge policy is loaded but missing allowed_ips — SSRF guard will deny"
+    fi
+  else
+    fail "agenticros_rosbridge policy is NOT loaded — run: nemoclaw nemo policy-add --yes --from-file scripts/agenticros-rosbridge.policy.yaml"
+  fi
+fi
+
+# ----- 3. rosbridge_server bound on host:9090 -------------------------------
+if ss -ltn 2>/dev/null | awk '{print $4}' | grep -qE '(:9090|:::9090|0\.0\.0\.0:9090)$'; then
+  pass "rosbridge_server is listening on host :9090"
+else
+  fail "nothing is listening on host :9090 — start the host stack: ./scripts/run_nemoclaw_host_stack.sh humble"
+fi
+
+# ----- 4. sandbox proxy decision for the plugin's binary --------------------
+LOG_FILE=$(docker exec "${CONTAINER}" sh -c 'ls -t /var/log/openshell.*.log 2>/dev/null | head -1' 2>/dev/null | tr -d '\r')
+if [[ -n "${LOG_FILE}" ]]; then
+  LAST_DECISION=$(docker exec "${CONTAINER}" sh -c "grep -E 'host.docker.internal:9090|host.openshell.internal:9090' '${LOG_FILE}' | tail -1" 2>/dev/null)
+  if [[ -z "${LAST_DECISION}" ]]; then
+    warn "no recent proxy decisions for host.docker.internal:9090 in ${LOG_FILE} (gateway hasn't tried yet?)"
+  elif grep -qE 'ALLOWED.*policy:agenticros_rosbridge' <<<"${LAST_DECISION}"; then
+    pass "last proxy decision: ALLOWED via agenticros_rosbridge"
+  elif grep -q 'engine:ssrf' <<<"${LAST_DECISION}"; then
+    fail "last proxy decision: DENIED by SSRF guard — add allowed_ips to the policy. Saw: ${LAST_DECISION##*OCSF }"
+  elif grep -q 'engine:opa' <<<"${LAST_DECISION}"; then
+    fail "last proxy decision: DENIED by OPA — endpoint missing from agenticros_rosbridge. Saw: ${LAST_DECISION##*OCSF }"
+  else
+    warn "unrecognised proxy decision: ${LAST_DECISION##*OCSF }"
+  fi
+fi
+
+# ----- 5. live WebSocket roundtrip to /rosapi/topics through the proxy ------
+GW_PID=$(docker exec "${CONTAINER}" pgrep -f openclaw-gateway 2>/dev/null | head -1 | tr -d '\r')
+WS_PATH=$(docker exec "${CONTAINER}" sh -c 'ls -d /sandbox/agenticros/node_modules/.pnpm/ws@*/node_modules/ws 2>/dev/null | head -1' | tr -d '\r')
+if [[ -z "${GW_PID}" ]] || [[ -z "${WS_PATH}" ]]; then
+  warn "skip WebSocket roundtrip — gateway pid=${GW_PID:-?} ws=${WS_PATH:-?}"
+else
+  TOPICS_JSON=$(docker exec "${CONTAINER}" sh -c "nsenter --target ${GW_PID} --net -- node --input-type=commonjs -e '
+const http=require(\"http\");
+const WebSocket=require(\"${WS_PATH}\");
+const agent=new http.Agent({keepAlive:false});
+agent.createConnection=(opts,cb)=>{
+  const req=http.request({host:\"10.200.0.1\",port:3128,method:\"CONNECT\",path:opts.host+\":\"+opts.port,headers:{Host:opts.host+\":\"+opts.port}});
+  req.on(\"connect\",(res,sock)=>{ if(res.statusCode!==200){cb(new Error(\"proxy \"+res.statusCode));return;} cb(null,sock); });
+  req.on(\"error\",cb); req.end();
+};
+const ws=new WebSocket(\"ws://host.docker.internal:9090\",{agent});
+ws.on(\"open\",()=>ws.send(JSON.stringify({op:\"call_service\",service:\"/rosapi/topics\",id:\"smoke\"})));
+ws.on(\"message\",m=>{const o=JSON.parse(m.toString()); console.log(JSON.stringify({count:(o.values&&o.values.topics||[]).length, sample:(o.values&&o.values.topics||[]).slice(0,3)})); ws.close(); process.exit(0);});
+ws.on(\"error\",e=>{console.error(\"ERR\",e.message); process.exit(1);});
+setTimeout(()=>{console.error(\"timeout\"); process.exit(2);},6000);
+' 2>&1" 2>/dev/null | tail -1)
+  if grep -qE '^\{"count":[0-9]+' <<<"${TOPICS_JSON}"; then
+    pass "WebSocket roundtrip: $(jq -r '"\(.count) topics, sample=\(.sample|join(", "))"' <<<"${TOPICS_JSON}" 2>/dev/null || echo "${TOPICS_JSON}")"
+  else
+    fail "WebSocket roundtrip failed: ${TOPICS_JSON:-<no output>}"
+  fi
+fi
+
+# ----- 6. NemoClaw dashboard reachable + non-empty --------------------------
+DASH_URL=$(nemoclaw nemo dashboard-url --quiet 2>/dev/null | head -1 || true)
+DASH_BASE=${DASH_URL%%#*}
+if [[ -z "${DASH_BASE}" ]]; then
+  warn "dashboard URL not reported by nemoclaw (sandbox not Ready?)"
+else
+  DASH_BYTES=$(curl -fsS "${DASH_BASE}" 2>/dev/null | wc -c | tr -d ' ')
+  if [[ -n "${DASH_BYTES}" ]] && [[ "${DASH_BYTES}" -gt 200 ]]; then
+    pass "dashboard at ${DASH_BASE} returns ${DASH_BYTES}-byte body"
+    echo "    URL with token: ${DASH_URL}"
+  else
+    fail "dashboard at ${DASH_BASE} returned ${DASH_BYTES:-0} bytes — gateway crashed?"
+  fi
+fi
+
+echo
+echo "Summary: ${GREEN}${PASS} passed${RESET}, ${RED}${FAIL} failed${RESET}"
+[[ ${FAIL} -eq 0 ]]

package/runtime/scripts/start_demo.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# start_demo.sh - Prepare the AgenticROS Claude Code demo (local DDS transport).
+#
+# What this does:
+#   1. Sources ROS2 + the agenticros workspace
+#   2. Launches the RealSense camera in the background (logs to /tmp)
+#   3. Builds the @agenticros/claude-code MCP server
+#   4. Starts the robot's motor controller via `robotics start motors`
+#
+# After this finishes, launch Claude Code from the repo root. The MCP server
+# is auto-started by .mcp.json over stdio — nothing else to run on this host.
+#
+# Usage: ./scripts/start_demo.sh [jazzy|humble]
+
+set -e
+
+ROS_DISTRO="${1:-jazzy}"
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+CAMERA_LOG=/tmp/agenticros-camera.log
+CAMERA_PID_FILE=/tmp/agenticros-camera.pid
+source "$REPO_ROOT/scripts/lib/agenticros-banner.sh"
+
+agenticros_banner
+echo "Starting AgenticROS Claude Code demo"
+echo ""
+
+echo "==> Sourcing ROS2 ($ROS_DISTRO) and agenticros workspace"
+source "/opt/ros/$ROS_DISTRO/setup.bash"
+if [[ -f "$REPO_ROOT/ros2_ws/install/setup.bash" ]]; then
+    source "$REPO_ROOT/ros2_ws/install/setup.bash"
+else
+    echo "   (ros2_ws is not built — run: cd ros2_ws && colcon build --symlink-install)"
+fi
+
+echo "==> Starting RealSense camera (logs: $CAMERA_LOG)"
+if [[ -f "$CAMERA_PID_FILE" ]] && kill -0 "$(cat "$CAMERA_PID_FILE")" 2>/dev/null; then
+    echo "   Already running (pid $(cat "$CAMERA_PID_FILE")) — skipping"
+elif pgrep -f "realsense2_camera_node" >/dev/null; then
+    echo "   Detected an existing realsense2_camera_node — skipping"
+else
+    nohup ros2 launch realsense2_camera rs_launch.py >"$CAMERA_LOG" 2>&1 &
+    echo $! >"$CAMERA_PID_FILE"
+    echo "   Started (pid $(cat "$CAMERA_PID_FILE"))"
+fi
+
+echo "==> Building @agenticros/claude-code MCP server"
+cd "$REPO_ROOT"
+pnpm --filter @agenticros/claude-code build
+
+echo "==> Starting motor controller (robotics start motors)"
+robotics start motors
+
+echo ""
+echo "Demo ready. Launch Claude Code from $REPO_ROOT — .mcp.json starts the MCP server."
+echo "Stop the camera with: kill \$(cat $CAMERA_PID_FILE)"