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

Generic endpoint bindings and typed command frames now flow through planning, execution, routing, acknowledgement, cancellation, and safe-hold handling.

• Replaces temporary arm/tool routing with semantic slot and endpoint bindings.
• Adds transport-neutral runtime targets, payloads, frames, and mixed-transport routing.
• Updates built-in actions, planners, profiles, documentation, examples, and tests for the generalized runtime.

Confidence Score: 4/5

The PR does not yet appear safe to merge because a mixed-transport frame can partially begin execution before a later transport reports failure.

The outstanding router issue remains at the current head: transport groups are dispatched sequentially, while rejection is aggregated only after earlier transports may have accepted and acted; runner recovery occurs afterward and cannot restore frame-level atomicity.

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

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/transports.py	Introduces typed endpoint transport routing and acknowledgement aggregation, but multi-transport sends remain sequential and can partially execute before a later failure.
embodichain/lab/sim/atomic_actions/runner.py	Extends execution lifecycle handling to generic command frames and performs target-scoped cancel-then-hold recovery after dispatch failures.
embodichain/lab/sim/atomic_actions/runtime_commands.py	Defines immutable runtime targets, payloads, endpoint commands, synchronized frames, and timed command sequences.
embodichain/lab/sim/atomic_actions/bindings.py	Generalizes action bindings around semantic slot and endpoint identities with typed runtime targets.
embodichain/lab/sim/atomic_actions/engine.py	Adds engine-owned generic binding and invocation construction paths while preserving profile and direct-control-part resolution.

Sequence Diagram

sequenceDiagram
participant Runner
participant Router
participant TransportA
participant TransportB
Runner->>Router: send(frame)
Router->>TransportA: send(subframe A)
TransportA-->>Router: accepted
Router->>TransportB: send(subframe B)
TransportB-->>Router: rejected / timed out
Router-->>Runner: aggregate failure
Runner->>Router: cancel(all armed targets)
Runner->>Router: hold(all armed targets)

Loading

_{Reviews (7): Last reviewed commit: "wip" | 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.