Enables pipelined IsaacTeleop retargeting

[hougantc-nvda]

This PR improves IsaacLab Teleop retargeting performance and installation reliability.

• Added configurable IsaacTeleop retargeting execution via IsaacTeleopCfg.retargeting_execution.
• Enabled deadline-paced pipelined retargeting by default, so IsaacTeleop retargeting work can overlap with Isaac Lab simulation stepping.
• Preserved synchronous retargeting as an opt-in mode for exact current-frame behavior.
• Fixed IsaacTeleop retargeting support detection.
• Added an extension-level pip_upgrade_dependencies setting in extension.toml so ./isaaclab.sh --install can explicitly upgrade selected install_requires dependencies after editable install.
• Used that mechanism for isaaclab_teleop to upgrade to the latest compatible isaacteleop without duplicating the version spec outside setup.py.

Why

The pipelined retargeting path reduces Python-side frame pressure by returning the latest completed retargeting output while the current frame is submitted in parallel.

The install change fixes CI/local environments where an older compatible isaacteleop version is already installed. Since pip install -e source/isaaclab_teleop does not upgrade already-satisfied dependencies by default, CI could keep using a stale IsaacTeleop package. The new targeted upgrade keeps the version range in setup.py as the source of truth while still allowing the install command to refresh isaacteleop.

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
List any dependencies that are required for this change.

Fixes # (issue)

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

Please attach before and after screenshots of the change if applicable.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This PR adds support for IsaacTeleop's pipelined retargeting execution mode, allowing retargeting to run on a worker thread instead of blocking the simulation loop. The implementation correctly handles backward compatibility with older IsaacTeleop versions that don't expose RetargetingExecutionConfig, falling back gracefully with appropriate warnings. The code is well-structured with proper feature detection and comprehensive test coverage.

Architecture Impact

Self-contained within isaaclab_teleop. The changes affect:

1. IsaacTeleopCfg - adds new retargeting_execution field with smart default
2. TeleopSessionLifecycle._try_start_session() - passes the config to TeleopSessionConfig when supported
3. No external callers are broken - the new field has a default factory that handles both old and new IsaacTeleop versions transparently

Implementation Verdict

Ship it - Clean implementation with proper feature detection, graceful fallback, and thorough test coverage.

Test Coverage

Thorough. The new TestRetargetingExecutionConfig class covers:

• Default value when IsaacTeleop supports the API (test_cfg_defaults_to_pipelined_retargeting)
• Default value when IsaacTeleop lacks the API (test_cfg_defaults_to_none_with_legacy_isaacteleop)
• Config propagation to session (test_session_config_receives_cfg_retargeting_execution)
• Graceful omission for legacy IsaacTeleop with warning (test_session_config_omits_retargeting_execution_for_legacy_isaacteleop)
• Error propagation from supported IsaacTeleop (test_session_config_propagates_typeerror_from_supported_isaacteleop)

The test stub setup correctly adds RetargetingExecutionConfig to the mocked isaacteleop.teleop_session_manager module.

CI Status

No CI checks available yet.

Findings

🔵 Improvement: source/isaaclab_teleop/isaaclab_teleop/session_lifecycle.py:495-504 — Consider catching TypeError for unsupported kwargs

The current logic warns when _RETARGETING_EXECUTION_SUPPORTED is False but cfg.retargeting_execution is set. However, if a user has an older IsaacTeleop and somehow bypasses the default factory to set a non-None value, the code silently drops it. This is actually the correct behavior as tested, but a debug log might help users understand why their setting was ignored:

else:
    logger.warning(
        "Installed IsaacTeleop does not support retargeting_execution; "
        "using its default retargeting behavior."
    )
    # Current: correctly omits from extra_kwargs

This is already handled correctly - just noting the logic is sound.

🔵 Improvement: source/isaaclab_teleop/isaaclab_teleop/isaac_teleop_cfg.py:43-46 — Type annotation could be more precise

The retargeting_execution field uses Any | None which is correct for cross-version compatibility, but the docstring could include a type hint comment for IDE support:

retargeting_execution: Any | None = field(default_factory=_default_retargeting_execution_config)
"""IsaacTeleop retargeting execution settings.
...
Type: ``RetargetingExecutionConfig | None`` when isaacteleop >= X.Y.Z
"""

This is minor - the current approach is pragmatic given the dynamic nature of the dependency.

🔵 Improvement: source/isaaclab_teleop/test/test_cloudxr_lifecycle.py:74-80 — Test stub dataclass could match real API more closely

The stub RetargetingExecutionConfig defaults mode="sync", but the production default is "pipelined". While this doesn't affect test correctness (tests explicitly check the factory-produced default), matching the real API's signature would make the stub more authentic:

@dataclass
class RetargetingExecutionConfig:
    mode: str = "pipelined"  # Match real default if known

This is cosmetic - the tests correctly verify the behavior regardless.

🔵 Improvement: source/isaaclab_teleop/changelog.d/hougantc-pipelined-retargeting.rst — Consider adding migration note

The changelog correctly documents the change, but a brief note about how existing configs are affected would help users:

Changed
^^^^^^^

* Changed :class:`~isaaclab_teleop.IsaacTeleopCfg` to enable IsaacTeleop
  pipelined retargeting by default when supported by the installed
  IsaacTeleop version. Set
  ``retargeting_execution=RetargetingExecutionConfig(mode="sync")`` to restore
  exact current-frame retargeting.

  .. note::
     Existing configs without explicit ``retargeting_execution`` will automatically
     use pipelined mode. This is backward compatible with older IsaacTeleop versions.

[greptile-apps]

Greptile Summary

This PR introduces pipelined IsaacTeleop retargeting by default via a new retargeting_execution field on IsaacTeleopCfg, and adds a pip_upgrade_dependencies mechanism in the install CLI so extensions can request that specific dependencies be upgraded to their latest compatible version after the editable install.

• Pipelined retargeting: IsaacTeleopCfg.retargeting_execution defaults to RetargetingExecutionConfig(mode=\"pipelined\", pacing=DeadlinePacingConfig(safety_margin_s=0.025)) and is forwarded to TeleopSessionConfig in session_lifecycle.py. The import of RetargetingExecutionConfig/DeadlinePacingConfig is unconditional at module load time, but the PR claims graceful fallback on older IsaacTeleop installs \u2014 which is not implemented.
• pip_upgrade_dependencies install hook: New helpers in install.py read a list of dependency names from [isaac_lab_settings] pip_upgrade_dependencies in extension.toml, resolve their full requirement strings from installed distribution metadata, and run a targeted pip install --upgrade after the editable install.

Confidence Score: 3/5

The unconditional import and unconditional kwarg in the retargeting integration will break any environment with an older IsaacTeleop install that predates RetargetingExecutionConfig.

The install-side pip_upgrade_dependencies logic is solid and well-tested, but the module-level import in isaac_teleop_cfg.py and the TeleopSessionConfig call site in session_lifecycle.py have no backward-compat guards, so any older IsaacTeleop environment fails to load the extension entirely. The PR description explicitly promises a fallback for older installs, making the gap a meaningful correctness concern.

source/isaaclab_teleop/isaaclab_teleop/isaac_teleop_cfg.py and source/isaaclab_teleop/isaaclab_teleop/session_lifecycle.py both need backward-compat guards for the RetargetingExecutionConfig import and kwarg.

Important Files Changed

Filename	Overview
source/isaaclab_teleop/isaaclab_teleop/isaac_teleop_cfg.py	Adds retargeting_execution field defaulting to pipelined mode, but imports RetargetingExecutionConfig/DeadlinePacingConfig unconditionally, breaking older IsaacTeleop installs at module-load time despite the PR's backward-compat claim.
source/isaaclab_teleop/isaaclab_teleop/session_lifecycle.py	Passes retargeting_execution kwarg unconditionally to TeleopSessionConfig; older IsaacTeleop versions that don't accept this argument will raise TypeError on every session-start attempt.
source/isaaclab/isaaclab/cli/commands/install.py	Adds pip_upgrade_dependencies support: reads target dependency names from extension.toml, looks up their full requirement strings from installed distribution metadata, and upgrades them with pip/uv after the editable install. Logic is clean with proper normalization and deduplication.
source/isaaclab/test/cli/test_install_commands.py	Comprehensive unit tests for the new pip_upgrade_dependencies install flow covering pip and uv paths, deduplication, missing metadata warnings, and invalid TOML types.
source/isaaclab_teleop/test/test_cloudxr_lifecycle.py	Adds stub infrastructure for DeadlinePacingConfig/RetargetingExecutionConfig and a new test verifying that the default config is forwarded to TeleopSessionConfig; does not test the fallback path promised in the PR description.

_{Reviews (2): Last reviewed commit: "fix: Upgrade teleop dependency during in..." | Re-trigger Greptile}

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This is a follow-up review. The previous review found no blocking issues - only minor improvement suggestions. The new commit (aa04e7b) appears identical to the previous review state based on the diff and file contents.

Implementation Verdict

Ship it - No new issues introduced. The previous improvement suggestions were optional/cosmetic (better docstring type hints, changelog migration notes, test stub defaults). The core implementation is correct with proper feature detection, graceful fallback for older IsaacTeleop versions, and comprehensive test coverage.

CI Status

Core checks passing (pre-commit ✅, changelog fragments ✅, wheel build ✅). Infrastructure checks still pending but unrelated to code correctness.

[rwiltz]

@greptile

[isaaclab-review-bot]

Code Review

Thanks for this PR enabling pipelined IsaacTeleop retargeting! The deadline-paced execution approach is a solid optimization for reducing GIL contention. A few observations:

🔴 Potential Import-Time Compatibility Issue

File: source/isaaclab_teleop/isaaclab_teleop/isaac_teleop_cfg.py

The PR description states it should "Fall back to the historical IsaacTeleop execution path on older installs that do not expose RetargetingExecutionConfig." However, the import at line 15:

from isaacteleop.teleop_session_manager import DeadlinePacingConfig, RetargetingExecutionConfig

is unconditional. This will raise an ImportError when loading IsaacTeleopCfg on older isaacteleop versions that don't have these classes, rather than falling back gracefully.

Suggested fix: Consider wrapping this import in a try/except block with a fallback (e.g., defining stub dataclasses or setting them to None) and adjusting session_lifecycle.py to handle the None case by omitting the retargeting_execution kwarg when calling TeleopSessionConfig.

🟡 Test Coverage Note

The tests stub out DeadlinePacingConfig and RetargetingExecutionConfig in the test fixtures, which is reasonable for unit testing but means CI won't catch the import-time failure scenario described above. Consider adding an integration test that verifies the module imports cleanly in environments with older isaacteleop versions (or without isaacteleop installed, if that's a supported configuration).

🟢 Well-Designed Features

1. Install upgrade mechanism: The pip_upgrade_dependencies feature in extension.toml is cleanly implemented with proper PEP 503 name normalization, metadata parsing, and support for both pip and uv. Good test coverage here.

2. Documentation: Comprehensive updates to RST docs, README, and changelogs explaining the 25ms safety margin rationale.

3. Configuration design: The RetargetingExecutionConfig integration with IsaacTeleopCfg follows the existing dataclass pattern well, with sensible defaults.