refactor(atomic-actions): generalize runtime endpoints

[yuecideng]

Description

Stack

• Layer: 2/14
• Base: main
• Depends on: feat(sim): add declarative scene and robot skill foundation #487 (merged as 18fd07e5)
• Followed by: feat(sim): add semantic skill IR and compiler #492

Make generic profile endpoints executable end to end. Bindings are keyed by semantic slots and endpoint IDs; typed runtime targets and payloads flow through command frames, routers, transports, acknowledgements, cancellation, and transport-owned safe holds.

This intentionally removes the temporary arm/tool-shaped routing seam. Joint-position, full-body, and custom endpoint tests all use the same authorization and lifecycle contracts.

Integration

Rebased onto main after #517 and #487 were squash-merged. Conflict resolution preserves #517's num_envs interfaces, engine-local registry, and unified HeldObjectState exclusivity semantics while applying this layer's generic endpoint and transport runtime.

Refs #471
Refs #474

Type of change

• Breaking change (the temporary arm/tool runtime binding API is removed)

Screenshots

Not applicable.

Validation

• Affected regression: 510 passed, 5 skipped, 4 deselected
• Black 26.3.1: all 670 Python files unchanged
• Changed Python files: Apache headers 61/61, future annotations 61/61, and public-module exports pass
• Sphinx HTML build: successful (warnings are pre-existing/non-fatal)
• Full repository suite is delegated to the new GitHub CI run for this updated head

Checklist

• Code passes Black 26.3.1.
• Corresponding public/design documentation is included in this layer.
• Tests cover the affected behavior.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR replaces the temporary arm/tool routing seam with typed, semantic runtime endpoints and carries generic endpoint commands through planning, execution, transport routing, acknowledgements, cancellation, and safe holds.

• Introduces immutable runtime endpoint targets, payloads, command frames, and timed command sequences.
• Adds transport-neutral routing and transport-owned cancellation and hold operations.
• Migrates action bindings, built-in actions, profiles, integrations, tests, and documentation to semantic slot and endpoint identifiers.

Confidence Score: 4/5

The PR is not yet safe to merge because multi-transport frames can still execute partially before failure recovery starts.

The router invokes transports sequentially and aggregates their acknowledgements afterward, so an earlier controller may begin executing before a later controller rejects or fails; the runner subsequently cancels and holds all recorded targets, but that recovery does not restore synchronized all-or-none dispatch.

Files Needing Attention: embodichain/lab/sim/atomic_actions/transports.py

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/transports.py	Adds generic endpoint transport routing, acknowledgement aggregation, cancellation, and safe holds; the previously reported partial multi-transport execution remains possible.
embodichain/lab/sim/atomic_actions/runtime_commands.py	Defines immutable transport-neutral targets, payloads, command frames, and timed command sequences with validation and snapshot ownership.
embodichain/lab/sim/atomic_actions/runner.py	Updates execution dispatch and best-effort cancel-then-hold recovery to operate on runtime endpoint targets.
embodichain/lab/sim/atomic_actions/bindings.py	Generalizes action bindings around semantic slot and endpoint keys backed by typed runtime targets.
embodichain/lab/sim/skills/profiles.py	Migrates declarative robot resource resolution to generic endpoint targets and binding metadata.

_{Reviews (2): Last reviewed commit: "refactor(atomic-actions): generalize run..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Refactors the atomic-actions runtime to execute transport-neutral endpoint command frames end-to-end (bindings → planning → session → runner → transport router), removing the temporary arm/tool-shaped binding seam and making runtime targets/payloads first-class.

Changes:

• Replaces role-based ActionBinding usage with engine-owned endpoint bindings via SkillBindingContract + engine.bind_control_parts(...).
• Introduces/threads transport-neutral runtime command carriers (RuntimeCommandFrame, TimedCommandSequence) through planning and execution, including safe-stop behavior via endpoint targets.
• Updates built-in primitives, tests, tutorials, benchmarks, and docs to the new binding + runtime command model.

Reviewed changes

Copilot reviewed 69 out of 69 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/sim/planners/test_curobo_planner.py	Updates planner tests to use engine.bind_control_parts() bindings.
tests/sim/atomic_actions/test_sim_adapter.py	Adapts sim adapter tests to endpoint command frames/targets and transport semantics.
tests/sim/atomic_actions/test_runtime_commands.py	Adds value-object tests for transport-neutral runtime commands.
tests/sim/atomic_actions/test_runner.py	Updates runner tests for endpoint frames, target-scoped hold/cancel, and revision staging.
tests/sim/atomic_actions/test_motion_strategy_e2e.py	Adjusts e2e assertions to use per-plan joint trajectory + command sequence.
tests/sim/atomic_actions/test_engine.py	Updates engine tests for direct endpoint binding and joint-trajectory-only compilation.
tests/sim/atomic_actions/test_curobo_motion_strategy_e2e.py	Updates curobo e2e to new binding and plan output structure.
tests/sim/atomic_actions/test_control.py	Migrates command override and binding resolution tests to endpoint-scoped overrides.
scripts/tutorials/atomic_action/press.py	Migrates tutorial to bind_control_parts() and per-skill bindings.
scripts/tutorials/atomic_action/place.py	Migrates tutorial to bind_control_parts() and endpoint mappings.
scripts/tutorials/atomic_action/pickup.py	Migrates tutorial invocation binding to endpoint binding helper.
scripts/tutorials/atomic_action/moving_target_recovery.py	Updates recovery tutorial to new binding API.
scripts/tutorials/atomic_action/move_joints.py	Updates tutorial to endpoint binding helper for joint motion.
scripts/tutorials/atomic_action/move_held_object.py	Updates tutorial to per-skill endpoint bindings.
scripts/tutorials/atomic_action/move_end_effector.py	Updates tutorial to endpoint binding helper.
scripts/tutorials/atomic_action/hand_over.py	Updates tutorial to endpoint bindings for source/destination slots.
scripts/tutorials/atomic_action/dynamic_obstacle_recovery.py	Switches EEF path computation from trajectory to command sequence; updates binding.
scripts/tutorials/atomic_action/coordinated_placement.py	Updates coordinated placement tutorial to new bindings and trajectory retrieval.
scripts/tutorials/atomic_action/coordinated_pickment.py	Updates coordinated pickment tutorial to new endpoint binding.
scripts/tutorials/atomic_action/assemble.py	Updates assemble tutorial to per-skill endpoint bindings.
scripts/benchmark/atomic_action/press_benchmark.py	Migrates benchmark to endpoint bindings per invocation sequence.
scripts/benchmark/atomic_action/place_benchmark.py	Migrates benchmark to endpoint binding helper.
scripts/benchmark/atomic_action/pickup_benchmark.py	Migrates benchmark to endpoint binding helper.
scripts/benchmark/atomic_action/move_joints_benchmark.py	Updates benchmark helpers to accept engine and build endpoint binding once.
scripts/benchmark/atomic_action/move_held_object_benchmark.py	Migrates benchmark to endpoint bindings for each skill.
scripts/benchmark/atomic_action/move_end_effector_benchmark.py	Migrates benchmark to endpoint binding helper.
examples/sim/planners/curobo_planner.py	Updates example to bind endpoints via engine helper.
embodichain/lab/sim/skills/profiles.py	Refactors profile endpoint resolution to produce typed runtime targets and binding endpoints.
embodichain/lab/sim/atomic_actions/sim_adapter.py	Implements joint-position endpoint transport behavior over RuntimeCommandFrame.
embodichain/lab/sim/atomic_actions/runtime.py	Reworks planning services to build/validate endpoint bindings and apply endpoint-scoped overrides.
embodichain/lab/sim/atomic_actions/runner.py	Updates runner to dispatch endpoint frames, target-scoped hold/cancel, and staged revision install.
embodichain/lab/sim/atomic_actions/requirements.py	Removes ActionBindingRoute lowering seam from endpoint requirements/contracts.
embodichain/lab/sim/atomic_actions/primitives/press.py	Migrates primitive to endpoint binding accessors/targets.
embodichain/lab/sim/atomic_actions/primitives/place.py	Migrates primitive to endpoint binding accessors/targets.
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Migrates primitive to endpoint binding accessors/targets and target-based DOF handling.
embodichain/lab/sim/atomic_actions/primitives/move_joints.py	Migrates primitive to endpoint binding accessors/targets.
embodichain/lab/sim/atomic_actions/primitives/move_held_object.py	Migrates primitive to endpoint binding accessors/targets.
embodichain/lab/sim/atomic_actions/primitives/move_end_effector.py	Migrates primitive to endpoint binding accessors/targets.
embodichain/lab/sim/atomic_actions/primitives/hand_over.py	Migrates primitive to endpoint binding accessors/targets for source/destination.
embodichain/lab/sim/atomic_actions/primitives/coordinated_placement.py	Migrates primitive to endpoint binding accessors/targets for placing/support.
embodichain/lab/sim/atomic_actions/primitives/coordinated_pickment.py	Migrates primitive to endpoint binding accessors/targets for left/right roles.
embodichain/lab/sim/atomic_actions/plans.py	Makes ActionPlan.commands authoritative (command sequences), adds feedback mode + optional joint trajectory retention.
embodichain/lab/sim/atomic_actions/invocation.py	Updates resolved request binding type and snapshots engine-owned endpoint bindings.
embodichain/lab/sim/atomic_actions/engine.py	Adds bind_control_parts() and constrains compile() to joint-trajectory-backed plans.
embodichain/lab/sim/atomic_actions/control.py	Reworks invocation command overrides to be endpoint-scoped and flattenable.
embodichain/lab/sim/atomic_actions/init.py	Updates public exports to new endpoint binding/command/transport types.
embodichain_tasks/embodichain_tasks/tableware/stack_blocks_two.py	Migrates task planning to per-skill endpoint bindings.
embodichain_tasks/embodichain_tasks/tableware/blocks_ranking_rgb.py	Migrates task planning to per-skill endpoint bindings.
embodichain_tasks/embodichain_tasks/multi_segments/cube_pick_place.py	Migrates multi-segment planning to per-skill endpoint bindings.
docs/source/tutorial/atomic_actions.rst	Updates tutorial docs for new binding contract, router usage, and revised runtime carriers.
docs/source/overview/sim/atomic_actions/robot_skill_profiles.md	Updates profile docs to remove lowering routes and describe typed runtime targets/bindings.
docs/source/api_reference/embodichain/embodichain.lab.sim.atomic_actions.rst	Updates API reference exports for new endpoint runtime types and router/transport.
docs/design/declarative_expert_program_plan.md	Updates design doc to reflect PR2C runtime endpoint model and artifacts.
agent_context/MAP.yaml	Updates agent context index keywords for new runtime endpoint types.
.agents/skills/add-atomic-action/SKILL.md	Updates scaffolding guidance to the new endpoint binding + runtime command model.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.