agenticros 0.1.0 → 0.1.1

package/runtime/ros2_ws/src/agenticros_sim/models/agenticros_amr/model.sdf

@@ -0,0 +1,244 @@
+<?xml version="1.0"?>
+<!--
+  agenticros_amr/model.sdf
+  Two-wheel differential-drive AMR with:
+    * Chassis link (rectangular)
+    * Two driven wheels + one passive caster
+    * Forward-facing RGB-D camera (RealSense D435-ish: 640x480 colour + 16-bit depth)
+    * 2D GPU lidar (RPLidar-like, 360°, 12 Hz)
+    * IMU
+    * gz-sim diff-drive + odometry + joint-state systems
+
+  Topic layout (Gazebo side; ros_gz_bridge translates to ROS):
+    cmd_vel               → /model/agenticros_amr/cmd_vel
+    odom                  → /model/agenticros_amr/odometry
+    tf                    → /model/agenticros_amr/tf
+    rgb image             → /camera/camera/color/image_raw      (matches real RealSense)
+    rgb camera_info       → /camera/camera/color/camera_info
+    depth image (16UC1)   → /camera/camera/depth/image_rect_raw
+    depth camera_info     → /camera/camera/depth/camera_info
+    lidar scan            → /scan
+    imu                   → /imu/data
+-->
+<sdf version="1.10">
+  <model name="agenticros_amr">
+
+    <!-- ===================== Chassis ===================== -->
+    <link name="base_link">
+      <pose>0 0 0.10 0 0 0</pose>
+      <inertial>
+        <mass>5.0</mass>
+        <inertia>
+          <ixx>0.10</ixx><iyy>0.15</iyy><izz>0.20</izz>
+          <ixy>0</ixy><ixz>0</ixz><iyz>0</iyz>
+        </inertia>
+      </inertial>
+      <collision name="chassis_col">
+        <geometry><box><size>0.40 0.30 0.15</size></box></geometry>
+      </collision>
+      <visual name="chassis_vis">
+        <geometry><box><size>0.40 0.30 0.15</size></box></geometry>
+        <material><ambient>0.2 0.2 0.25 1</ambient><diffuse>0.3 0.3 0.35 1</diffuse></material>
+      </visual>
+
+      <!-- ============ RealSense-D435-like depth camera ============ -->
+      <!--
+        Mounted at front of the chassis, 0.10 m above the chassis top, looking
+        forward (+X). HFOV 87° matches the real D435 depth sensor; FOLLOW_ME
+        depth-loop code already assumes this HFOV constant.
+      -->
+      <sensor name="depth_camera" type="rgbd_camera">
+        <pose>0.20 0 0.18 0 0 0</pose>
+        <topic>camera</topic>
+        <update_rate>30</update_rate>
+        <camera>
+          <horizontal_fov>1.5184</horizontal_fov>
+          <image>
+            <width>640</width>
+            <height>480</height>
+            <format>R8G8B8</format>
+          </image>
+          <clip>
+            <near>0.10</near>
+            <far>10.0</far>
+          </clip>
+          <distortion>
+            <k1>0.0</k1><k2>0.0</k2><k3>0.0</k3><p1>0.0</p1><p2>0.0</p2>
+          </distortion>
+          <optical_frame_id>camera_optical_link</optical_frame_id>
+          <depth_camera>
+            <output>depths</output>
+          </depth_camera>
+        </camera>
+        <always_on>true</always_on>
+        <visualize>false</visualize>
+      </sensor>
+
+      <!-- ============ 2D GPU lidar (RPLidar-ish) ============ -->
+      <sensor name="gpu_lidar" type="gpu_lidar">
+        <pose>0 0 0.20 0 0 0</pose>
+        <topic>scan</topic>
+        <update_rate>12</update_rate>
+        <lidar>
+          <scan>
+            <horizontal>
+              <samples>360</samples>
+              <resolution>1</resolution>
+              <min_angle>-3.14159</min_angle>
+              <max_angle>3.14159</max_angle>
+            </horizontal>
+          </scan>
+          <range>
+            <min>0.10</min>
+            <max>12.0</max>
+            <resolution>0.01</resolution>
+          </range>
+          <noise>
+            <type>gaussian</type><mean>0.0</mean><stddev>0.01</stddev>
+          </noise>
+          <frame_id>lidar_link</frame_id>
+        </lidar>
+        <always_on>true</always_on>
+        <visualize>false</visualize>
+      </sensor>
+
+      <!-- ============ IMU ============ -->
+      <sensor name="imu_sensor" type="imu">
+        <pose>0 0 0 0 0 0</pose>
+        <topic>imu</topic>
+        <update_rate>100</update_rate>
+        <imu>
+          <angular_velocity>
+            <x><noise type="gaussian"><mean>0.0</mean><stddev>0.0005</stddev></noise></x>
+            <y><noise type="gaussian"><mean>0.0</mean><stddev>0.0005</stddev></noise></y>
+            <z><noise type="gaussian"><mean>0.0</mean><stddev>0.0005</stddev></noise></z>
+          </angular_velocity>
+          <linear_acceleration>
+            <x><noise type="gaussian"><mean>0.0</mean><stddev>0.005</stddev></noise></x>
+            <y><noise type="gaussian"><mean>0.0</mean><stddev>0.005</stddev></noise></y>
+            <z><noise type="gaussian"><mean>0.0</mean><stddev>0.005</stddev></noise></z>
+          </linear_acceleration>
+        </imu>
+        <always_on>true</always_on>
+      </sensor>
+    </link>
+
+    <!-- ===================== Left wheel ===================== -->
+    <link name="left_wheel_link">
+      <pose>0 0.18 0.08 -1.5707 0 0</pose>
+      <inertial>
+        <mass>0.5</mass>
+        <inertia><ixx>0.0008</ixx><iyy>0.0008</iyy><izz>0.0015</izz><ixy>0</ixy><ixz>0</ixz><iyz>0</iyz></inertia>
+      </inertial>
+      <collision name="col">
+        <geometry><cylinder><radius>0.08</radius><length>0.04</length></cylinder></geometry>
+        <surface><friction><ode><mu>1.0</mu><mu2>1.0</mu2></ode></friction></surface>
+      </collision>
+      <visual name="vis">
+        <geometry><cylinder><radius>0.08</radius><length>0.04</length></cylinder></geometry>
+        <material><ambient>0.1 0.1 0.1 1</ambient><diffuse>0.15 0.15 0.15 1</diffuse></material>
+      </visual>
+    </link>
+
+    <!-- ===================== Right wheel ===================== -->
+    <link name="right_wheel_link">
+      <pose>0 -0.18 0.08 -1.5707 0 0</pose>
+      <inertial>
+        <mass>0.5</mass>
+        <inertia><ixx>0.0008</ixx><iyy>0.0008</iyy><izz>0.0015</izz><ixy>0</ixy><ixz>0</ixz><iyz>0</iyz></inertia>
+      </inertial>
+      <collision name="col">
+        <geometry><cylinder><radius>0.08</radius><length>0.04</length></cylinder></geometry>
+        <surface><friction><ode><mu>1.0</mu><mu2>1.0</mu2></ode></friction></surface>
+      </collision>
+      <visual name="vis">
+        <geometry><cylinder><radius>0.08</radius><length>0.04</length></cylinder></geometry>
+        <material><ambient>0.1 0.1 0.1 1</ambient><diffuse>0.15 0.15 0.15 1</diffuse></material>
+      </visual>
+    </link>
+
+    <!-- ===================== Caster (passive front wheel) ===================== -->
+    <link name="caster_link">
+      <pose>0.16 0 0.04 0 0 0</pose>
+      <inertial>
+        <mass>0.1</mass>
+        <inertia><ixx>0.00004</ixx><iyy>0.00004</iyy><izz>0.00004</izz><ixy>0</ixy><ixz>0</ixz><iyz>0</iyz></inertia>
+      </inertial>
+      <collision name="col">
+        <geometry><sphere><radius>0.04</radius></sphere></geometry>
+        <surface><friction><ode><mu>0.05</mu><mu2>0.05</mu2></ode></friction></surface>
+      </collision>
+      <visual name="vis">
+        <geometry><sphere><radius>0.04</radius></sphere></geometry>
+        <material><ambient>0.1 0.1 0.1 1</ambient><diffuse>0.15 0.15 0.15 1</diffuse></material>
+      </visual>
+    </link>
+
+    <!-- ===================== Joints ===================== -->
+    <joint name="left_wheel_joint" type="revolute">
+      <parent>base_link</parent>
+      <child>left_wheel_link</child>
+      <axis>
+        <xyz>0 0 1</xyz>
+        <limit><lower>-1e16</lower><upper>1e16</upper></limit>
+      </axis>
+    </joint>
+
+    <joint name="right_wheel_joint" type="revolute">
+      <parent>base_link</parent>
+      <child>right_wheel_link</child>
+      <axis>
+        <xyz>0 0 1</xyz>
+        <limit><lower>-1e16</lower><upper>1e16</upper></limit>
+      </axis>
+    </joint>
+
+    <joint name="caster_joint" type="ball">
+      <parent>base_link</parent>
+      <child>caster_link</child>
+    </joint>
+
+    <!-- ===================== Plugins ===================== -->
+    <!--
+      Differential drive: subscribes to /model/agenticros_amr/cmd_vel and drives
+      the wheels. Publishes /model/agenticros_amr/odometry and tf as gz topics
+      that the bridge re-emits as ROS topics.
+    -->
+    <plugin filename="gz-sim-diff-drive-system" name="gz::sim::systems::DiffDrive">
+      <left_joint>left_wheel_joint</left_joint>
+      <right_joint>right_wheel_joint</right_joint>
+      <wheel_separation>0.36</wheel_separation>
+      <wheel_radius>0.08</wheel_radius>
+      <odom_publish_frequency>50</odom_publish_frequency>
+      <topic>cmd_vel</topic>
+      <odom_topic>odometry</odom_topic>
+      <tf_topic>tf</tf_topic>
+      <frame_id>odom</frame_id>
+      <child_frame_id>base_link</child_frame_id>
+      <max_linear_acceleration>1.0</max_linear_acceleration>
+      <max_angular_acceleration>2.0</max_angular_acceleration>
+    </plugin>
+
+    <plugin filename="gz-sim-joint-state-publisher-system" name="gz::sim::systems::JointStatePublisher">
+      <topic>joint_states</topic>
+    </plugin>
+
+    <!--
+      Pose publisher: every link's pose relative to the world. Useful for RViz
+      visualization without running robot_state_publisher with a URDF — but
+      note ROS tools generally expect /tf, which the diff-drive plugin
+      provides for the base + odom relationship.
+    -->
+    <plugin filename="gz-sim-pose-publisher-system" name="gz::sim::systems::PosePublisher">
+      <publish_link_pose>true</publish_link_pose>
+      <publish_sensor_pose>true</publish_sensor_pose>
+      <publish_collision_pose>false</publish_collision_pose>
+      <publish_visual_pose>false</publish_visual_pose>
+      <publish_nested_model_pose>false</publish_nested_model_pose>
+      <use_pose_vector_msg>true</use_pose_vector_msg>
+      <static_publisher>true</static_publisher>
+      <static_update_frequency>1</static_update_frequency>
+    </plugin>
+
+  </model>
+</sdf>

package/runtime/ros2_ws/src/agenticros_sim/package.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>agenticros_sim</name>
+  <version>0.1.0</version>
+  <description>
+    AgenticROS Gazebo Harmonic simulation assets: indoor world, 2-wheel AMR
+    model (depth camera + GPU lidar + IMU), ros_gz_bridge config that exposes
+    topics on AgenticROS' real-robot topic names, and a launch file that wires
+    it all together. Use with the agenticros CLI:  agenticros up sim-amr.
+  </description>
+  <maintainer email="hello@plaipin.com">PlaiPin</maintainer>
+  <license>Apache-2.0</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+
+  <exec_depend>ros_gz_sim</exec_depend>
+  <exec_depend>ros_gz_bridge</exec_depend>
+  <exec_depend>ros_gz_image</exec_depend>
+  <exec_depend>robot_state_publisher</exec_depend>
+  <exec_depend>xacro</exec_depend>
+  <exec_depend>rviz2</exec_depend>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

package/runtime/ros2_ws/src/agenticros_sim/worlds/agenticros_indoor.sdf

@@ -0,0 +1,183 @@
+<?xml version="1.0"?>
+<!--
+  agenticros_indoor.sdf
+  Gazebo Harmonic 8.x indoor environment for testing AgenticROS' sim AMR.
+
+  Layout:
+    * 12 m x 12 m floor with subtle walls (so SLAM-style demos have something
+      to localize against)
+    * Three free-standing cylinder + box obstacles inside the room so the
+      depth camera and LIDAR see non-trivial data
+    * One human-sized cylinder labeled "person" near the center — used by the
+      ros2_follow_me smoke test
+    * Standard physics + sensors + ros_gz system plugins so the AMR's depth
+      camera / IMU / lidar publish on Gazebo topics that the bridge picks up
+-->
+<sdf version="1.10">
+  <world name="agenticros_indoor">
+
+    <!-- ====== System plugins ====== -->
+    <plugin filename="gz-sim-physics-system" name="gz::sim::systems::Physics"/>
+    <plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
+      <render_engine>ogre2</render_engine>
+    </plugin>
+    <plugin filename="gz-sim-user-commands-system" name="gz::sim::systems::UserCommands"/>
+    <plugin filename="gz-sim-scene-broadcaster-system" name="gz::sim::systems::SceneBroadcaster"/>
+    <plugin filename="gz-sim-imu-system" name="gz::sim::systems::Imu"/>
+
+    <gravity>0 0 -9.81</gravity>
+
+    <gui fullscreen="false">
+      <plugin filename="MinimalScene" name="3D View">
+        <gz-gui>
+          <title>3D View</title>
+          <property type="bool" key="showTitleBar">false</property>
+          <property type="string" key="state">docked</property>
+        </gz-gui>
+        <engine>ogre2</engine>
+        <scene>scene</scene>
+        <ambient_light>0.4 0.4 0.4</ambient_light>
+        <background_color>0.8 0.8 0.8</background_color>
+        <camera_pose>-7 -7 6 0 0.6 0.78</camera_pose>
+      </plugin>
+    </gui>
+
+    <!-- ====== Lighting ====== -->
+    <light type="directional" name="sun">
+      <cast_shadows>true</cast_shadows>
+      <pose>0 0 10 0 0 0</pose>
+      <diffuse>0.9 0.9 0.9 1</diffuse>
+      <specular>0.2 0.2 0.2 1</specular>
+      <direction>-0.3 0.2 -0.9</direction>
+    </light>
+
+    <!-- ====== Ground ====== -->
+    <model name="ground_plane">
+      <static>true</static>
+      <link name="link">
+        <collision name="collision">
+          <geometry><plane><normal>0 0 1</normal><size>20 20</size></plane></geometry>
+        </collision>
+        <visual name="visual">
+          <geometry><plane><normal>0 0 1</normal><size>20 20</size></plane></geometry>
+          <material>
+            <ambient>0.6 0.6 0.6 1</ambient>
+            <diffuse>0.75 0.75 0.75 1</diffuse>
+            <specular>0.05 0.05 0.05 1</specular>
+          </material>
+        </visual>
+      </link>
+    </model>
+
+    <!-- ====== Walls (12m x 12m room, 2.5m tall, 0.15m thick) ====== -->
+    <model name="walls">
+      <static>true</static>
+      <link name="link">
+        <!-- North wall (+Y) -->
+        <collision name="north_col">
+          <pose>0 6 1.25 0 0 0</pose>
+          <geometry><box><size>12 0.15 2.5</size></box></geometry>
+        </collision>
+        <visual name="north_vis">
+          <pose>0 6 1.25 0 0 0</pose>
+          <geometry><box><size>12 0.15 2.5</size></box></geometry>
+          <material><ambient>0.85 0.85 0.9 1</ambient><diffuse>0.9 0.9 0.95 1</diffuse></material>
+        </visual>
+        <!-- South wall (-Y) -->
+        <collision name="south_col">
+          <pose>0 -6 1.25 0 0 0</pose>
+          <geometry><box><size>12 0.15 2.5</size></box></geometry>
+        </collision>
+        <visual name="south_vis">
+          <pose>0 -6 1.25 0 0 0</pose>
+          <geometry><box><size>12 0.15 2.5</size></box></geometry>
+          <material><ambient>0.85 0.85 0.9 1</ambient><diffuse>0.9 0.9 0.95 1</diffuse></material>
+        </visual>
+        <!-- East wall (+X) -->
+        <collision name="east_col">
+          <pose>6 0 1.25 0 0 0</pose>
+          <geometry><box><size>0.15 12 2.5</size></box></geometry>
+        </collision>
+        <visual name="east_vis">
+          <pose>6 0 1.25 0 0 0</pose>
+          <geometry><box><size>0.15 12 2.5</size></box></geometry>
+          <material><ambient>0.85 0.85 0.9 1</ambient><diffuse>0.9 0.9 0.95 1</diffuse></material>
+        </visual>
+        <!-- West wall (-X) -->
+        <collision name="west_col">
+          <pose>-6 0 1.25 0 0 0</pose>
+          <geometry><box><size>0.15 12 2.5</size></box></geometry>
+        </collision>
+        <visual name="west_vis">
+          <pose>-6 0 1.25 0 0 0</pose>
+          <geometry><box><size>0.15 12 2.5</size></box></geometry>
+          <material><ambient>0.85 0.85 0.9 1</ambient><diffuse>0.9 0.9 0.95 1</diffuse></material>
+        </visual>
+      </link>
+    </model>
+
+    <!-- ====== Person-sized cylinder (for ros2_follow_me depth-mode smoke test) ====== -->
+    <!--
+      Roughly human-shaped: 0.35 m radius, 1.7 m tall, centered ~2.5 m in front
+      of the AMR's spawn pose (the AMR spawns at origin facing +X by default).
+    -->
+    <model name="person_target">
+      <!-- Static so it doesn't drift or topple when nudged by the AMR. The
+           follow-me smoke test just needs a person-sized object in front of
+           the spawn pose; dynamics would make the smoke test flaky. -->
+      <static>true</static>
+      <pose>2.5 0 0.85 0 0 0</pose>
+      <link name="link">
+        <inertial>
+          <mass>60</mass>
+          <inertia><ixx>14.7</ixx><iyy>14.7</iyy><izz>3.7</izz><ixy>0</ixy><ixz>0</ixz><iyz>0</iyz></inertia>
+        </inertial>
+        <collision name="collision">
+          <geometry><cylinder><radius>0.35</radius><length>1.7</length></cylinder></geometry>
+        </collision>
+        <visual name="visual">
+          <geometry><cylinder><radius>0.35</radius><length>1.7</length></cylinder></geometry>
+          <material><ambient>0.7 0.4 0.3 1</ambient><diffuse>0.8 0.5 0.4 1</diffuse></material>
+        </visual>
+      </link>
+    </model>
+
+    <!-- ====== A few static obstacles to give the LIDAR / depth camera structure ====== -->
+    <model name="obstacle_box_1">
+      <static>true</static>
+      <pose>3 -2.5 0.4 0 0 0</pose>
+      <link name="link">
+        <collision name="c"><geometry><box><size>0.8 0.8 0.8</size></box></geometry></collision>
+        <visual name="v">
+          <geometry><box><size>0.8 0.8 0.8</size></box></geometry>
+          <material><ambient>0.3 0.5 0.7 1</ambient><diffuse>0.3 0.5 0.7 1</diffuse></material>
+        </visual>
+      </link>
+    </model>
+
+    <model name="obstacle_cyl_1">
+      <static>true</static>
+      <pose>-2 2.5 0.6 0 0 0</pose>
+      <link name="link">
+        <collision name="c"><geometry><cylinder><radius>0.35</radius><length>1.2</length></cylinder></geometry></collision>
+        <visual name="v">
+          <geometry><cylinder><radius>0.35</radius><length>1.2</length></cylinder></geometry>
+          <material><ambient>0.7 0.6 0.2 1</ambient><diffuse>0.8 0.7 0.2 1</diffuse></material>
+        </visual>
+      </link>
+    </model>
+
+    <model name="obstacle_box_2">
+      <static>true</static>
+      <pose>-3.5 -3 0.3 0 0 0</pose>
+      <link name="link">
+        <collision name="c"><geometry><box><size>1.2 0.6 0.6</size></box></geometry></collision>
+        <visual name="v">
+          <geometry><box><size>1.2 0.6 0.6</size></box></geometry>
+          <material><ambient>0.3 0.7 0.4 1</ambient><diffuse>0.3 0.8 0.4 1</diffuse></material>
+        </visual>
+      </link>
+    </model>
+
+  </world>
+</sdf>

package/runtime/scripts/configure_for_sim.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# configure_for_sim.sh
+#
+# One-shot helper: copy the simulation-tuned AgenticROS config template into
+# ~/.agenticros/config.json. Use this when you want the MCP server + OpenClaw
+# plugin to talk to the sim AMR's topics (which use no robot-namespace
+# prefix - so a fresh "real robot" config with a UUID namespace would miss
+# every topic).
+#
+# Usage:
+#   ./scripts/configure_for_sim.sh            # writes ~/.agenticros/config.json
+#   ./scripts/configure_for_sim.sh --backup   # back up an existing config first
+#   ./scripts/configure_for_sim.sh --print    # print the template to stdout
+#
+# After running, restart the MCP server (or run `agenticros up sim-amr`).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SRC="$ROOT/ros2_ws/src/agenticros_sim/config/agenticros-sim.config.json"
+DEST_DIR="$HOME/.agenticros"
+DEST="$DEST_DIR/config.json"
+
+PRINT_ONLY=false
+DO_BACKUP=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --print)   PRINT_ONLY=true; shift ;;
+    --backup)  DO_BACKUP=true; shift ;;
+    -h|--help) sed -n '2,16p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [[ ! -f "$SRC" ]]; then
+  echo "Template missing: $SRC" >&2
+  echo "Did you build the ros2 workspace? (cd $ROOT/ros2_ws && colcon build)" >&2
+  exit 1
+fi
+
+if [[ "$PRINT_ONLY" == "true" ]]; then
+  cat "$SRC"
+  exit 0
+fi
+
+mkdir -p "$DEST_DIR"
+
+if [[ -f "$DEST" ]]; then
+  if [[ "$DO_BACKUP" == "true" ]]; then
+    BAK="${DEST}.real.$(date +%Y%m%d-%H%M%S).bak"
+    cp -a "$DEST" "$BAK"
+    echo "[configure_for_sim] Backed up existing config -> $BAK"
+  else
+    echo "[configure_for_sim] $DEST already exists. Re-run with --backup to keep a copy." >&2
+    echo "[configure_for_sim] Aborting (use --backup to overwrite)." >&2
+    exit 1
+  fi
+fi
+
+cp "$SRC" "$DEST"
+echo "[configure_for_sim] Wrote $DEST"
+echo "[configure_for_sim] Inspect with: agenticros config show"
+echo "[configure_for_sim] Bring up sim with: agenticros up sim-amr"

package/runtime/scripts/sim/run_sim.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# scripts/sim/run_sim.sh
+#
+# Worker script invoked by `agenticros up sim-amr` (and later `sim-arm`). Sources
+# ROS 2 + the AgenticROS overlay, runs `ros2 launch agenticros_sim ...`, writes
+# its PID into /tmp/agenticros-sim.pid so `agenticros down` can stop it, and
+# tees output to /tmp/agenticros-sim.log so `agenticros logs sim` works.
+#
+# Usage:
+#   run_sim.sh --robot amr [--namespace sim_robot] [--rviz] [--no-gui]
+#
+# Flags:
+#   --robot amr|arm        Which sim launch to start (default: amr).
+#   --namespace <ns>       Robot namespace; exported as AGENTICROS_ROBOT_NAMESPACE.
+#   --rviz                 Bring up RViz alongside Gazebo.
+#   --no-gui               Run gz-sim headless (CI / docker).
+#   --ros-distro <distro>  Override ROS 2 distro (auto-detect by default).
+#   --colcon-ws <path>     Override the colcon workspace (default: <repo>/ros2_ws).
+#   --help                 Print this help and exit.
+#
+# Exit codes:
+#   0   sim exited cleanly
+#   1   missing dependency (gz, ros2, ros_gz_*, our launch file)
+#   2   bad CLI usage
+#   3   sim crashed at runtime — check /tmp/agenticros-sim.log
+
+# Strict mode, but `set -u` clashes with ROS setup scripts that reference
+# AMENT_TRACE_SETUP_FILES etc. We toggle nounset off around each `source`.
+set -eo pipefail
+shopt -s expand_aliases || true
+
+# ---------- args ----------
+ROBOT="amr"
+NAMESPACE=""
+USE_RVIZ="false"
+GUI="true"
+ROS_DISTRO_OVERRIDE=""
+COLCON_WS=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --robot)        ROBOT="$2"; shift 2 ;;
+    --namespace)    NAMESPACE="$2"; shift 2 ;;
+    --rviz)         USE_RVIZ="true"; shift ;;
+    --no-gui)       GUI="false"; shift ;;
+    --ros-distro)   ROS_DISTRO_OVERRIDE="$2"; shift 2 ;;
+    --colcon-ws)    COLCON_WS="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,24p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [[ "$ROBOT" != "amr" && "$ROBOT" != "arm" ]]; then
+  echo "--robot must be 'amr' or 'arm' (got '$ROBOT')" >&2
+  exit 2
+fi
+
+# ---------- paths ----------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+COLCON_WS="${COLCON_WS:-$REPO_ROOT/ros2_ws}"
+
+LOG_FILE="/tmp/agenticros-sim.log"
+PID_FILE="/tmp/agenticros-sim.pid"
+
+log() { printf "\033[36m[run_sim]\033[0m %s\n" "$*"; }
+err() { printf "\033[31m[run_sim]\033[0m %s\n" "$*" >&2; }
+
+# ---------- ROS 2 distro detection ----------
+if [[ -n "$ROS_DISTRO_OVERRIDE" ]]; then
+  ROS_DISTRO="$ROS_DISTRO_OVERRIDE"
+elif [[ -n "${ROS_DISTRO:-}" ]]; then
+  : # already sourced
+else
+  for d in humble jazzy iron rolling; do
+    if [[ -f "/opt/ros/$d/setup.bash" ]]; then ROS_DISTRO="$d"; break; fi
+  done
+fi
+if [[ -z "${ROS_DISTRO:-}" ]] || [[ ! -f "/opt/ros/$ROS_DISTRO/setup.bash" ]]; then
+  err "ROS 2 not found under /opt/ros/. Install Humble or Jazzy first."
+  exit 1
+fi
+
+log "ROS_DISTRO=$ROS_DISTRO"
+log "COLCON_WS=$COLCON_WS"
+log "robot=$ROBOT  namespace=${NAMESPACE:-<none>}  rviz=$USE_RVIZ  gui=$GUI"
+
+# shellcheck disable=SC1090
+source "/opt/ros/$ROS_DISTRO/setup.bash"
+
+# ---------- Build agenticros_sim if not yet built ----------
+if [[ ! -f "$COLCON_WS/install/agenticros_sim/share/agenticros_sim/launch/sim_amr.launch.py" ]]; then
+  log "agenticros_sim not built in $COLCON_WS — building now..."
+  (cd "$COLCON_WS" && colcon build --symlink-install --packages-select agenticros_sim agenticros_msgs)
+fi
+
+# shellcheck disable=SC1090
+source "$COLCON_WS/install/setup.bash"
+
+# ---------- Dependency checks ----------
+for bin in gz ros2 rviz2; do
+  if ! command -v "$bin" >/dev/null; then
+    if [[ "$bin" == "rviz2" ]] && [[ "$USE_RVIZ" != "true" ]]; then
+      continue
+    fi
+    err "Required binary '$bin' not found on PATH."
+    exit 1
+  fi
+done
+
+# ---------- Wire up environment ----------
+if [[ -n "$NAMESPACE" ]]; then
+  export AGENTICROS_ROBOT_NAMESPACE="$NAMESPACE"
+fi
+
+LAUNCH_ARGS=(
+  "use_rviz:=$USE_RVIZ"
+  "gui:=$GUI"
+)
+
+# ---------- Pick launch file ----------
+case "$ROBOT" in
+  amr) LAUNCH_FILE="sim_amr.launch.py" ;;
+  arm) LAUNCH_FILE="sim_arm.launch.py" ;;  # Phase 3
+esac
+
+if ! ros2 launch --help >/dev/null 2>&1; then
+  err "ros2 launch not available — is ROS sourced properly?"
+  exit 1
+fi
+
+log "Logging to $LOG_FILE"
+log "ros2 launch agenticros_sim $LAUNCH_FILE ${LAUNCH_ARGS[*]}"
+log "Press Ctrl+C to stop (or run \`agenticros down\` from another terminal)."
+
+# Run in foreground so Ctrl+C in the parent shell still works, but also tee to
+# the log so `agenticros logs sim -f` can follow concurrently. The PID we record
+# is this script's own PID so `agenticros down` SIGTERMs the whole subtree.
+echo "$$" > "$PID_FILE"
+
+# Use `exec` so the ros2 process replaces our shell — that way signals from the
+# CLI (or Ctrl+C) hit ros2 directly instead of bash.
+exec 1> >(tee -a "$LOG_FILE") 2>&1
+exec ros2 launch agenticros_sim "$LAUNCH_FILE" "${LAUNCH_ARGS[@]}"