feat: extract manipulation plan execution manager

[TomCC7]

Contribution path

• Linked issue or discussion: DIM-1355

Problem

Manipulation execution mixed plan interpretation, per-robot trajectory splitting, coordinator task selection, dispatch, rollback, cancellation, and status polling into ManipulationModule.

That design treated a coordinated plan as independently executable robot fragments. It also duplicated trajectory-task policy above the control coordinator, even though the coordinator owns the hardware state and arbitration needed to decide whether a trajectory is safe to start.

Solution

• Add PlanExecutionManager as the boundary between planning and control. It maps one complete GeneratedPlan from global planner joint names to coordinator joint names, serializes execute/cancel operations, and makes one coordinator RPC.
• Inject the blueprint's ControlCoordinator module reference into ManipulationModule and pass that framework-managed RPC proxy directly to PlanExecutionManager; no forwarding client or independently owned RPC lifecycle is needed.
• Require every ManipulationModule blueprint to include a ControlCoordinator. Remove the standalone xarm6-planner-only and dual-xarm6-planner blueprints in favor of their mock-capable coordinator-backed replacements.
• Give each ControlCoordinator exactly one JointTrajectoryTask. Multi-arm coordinators configure that task with the union of their controlled joints; single-arm subset plans remain valid.
• Add typed execution and cancellation results. Deterministic validation failures are rejections; RPC failures are UNCERTAIN because the remote operation may have occurred.
• Move executable-trajectory validation into JointTrajectoryTask, including a start-state check against coordinator-owned hardware positions. Configure start_position_tolerance through task parameters.
• Model immutable execution configuration with attrs, while retaining Pydantic at the untyped task-parameter boundary.
• Keep direct gripper commands separate from planned trajectory execution.

Breaking API and behavior changes

Before	Now	Migration / behavior
ManipulationModule.execute(robot_name=...)	execute()	Execution no longer accepts a robot/arm selector. It always dispatches the complete stored plan.
ManipulationModule.execute_plan(plan, robot_name=...)	execute_plan(plan)	Partial execution is expressed by planning for a subset of joints, not by filtering a coordinated plan at execution time. A multi-arm plan is dispatched atomically.
ManipulationModule.get_trajectory_status(robot_name=...)	Removed	The manipulation layer no longer exposes or polls coordinator task state. Acceptance is reported immediately; callers do not infer completion from a duration sleep.
RobotModelConfig.coordinator_task_name	Removed	Robot configs no longer route trajectories to named tasks. Configure one trajectory task on the coordinator instead.
CoordinatorClient.execute_trajectory(task_name, trajectory) -> bool	execute_trajectory(trajectory) -> TrajectoryExecutionResult	Remove the task name and handle semantic acceptance/rejection statuses. The interactive shell returns immediately after acceptance.
CoordinatorClient.cancel_trajectory(task_name) -> bool	cancel_trajectory() -> TrajectoryCancellationResult	Remove the task name and handle CANCELLED, ALREADY_STOPPED, NO_TRAJECTORY_TASK, or UNCERTAIN.
ManipulationModule could run without a coordinator	A ControlCoordinator module reference is required	Compose manipulation and control in the same blueprint. The framework injects the typed RPC proxy automatically.
xarm6-planner-only and dual-xarm6-planner	Removed	Use xarm7-planner-coordinator for a mock-capable single-arm planning stack or dual-xarm6-planner-coordinator for dual-arm planning.
Multiple JointTrajectoryTask instances per coordinator	One task per coordinator	Adding a second trajectory task raises ValueError. Multi-arm blueprints must create one task claiming all coordinated joints.
JointTrajectoryTask.execute(trajectory) -> bool	execute(trajectory, current_positions) -> TrajectoryExecutionResult	The coordinator supplies current hardware positions, and the task rejects missing or mismatched start state.

Generated-plan joint names remain globally scoped as <robot>/<local_joint>. ExecutionTarget resolves those names to coordinator joints; the caller no longer passes a robot ID during execution.

How to Test

uv run pytest dimos/control dimos/manipulation dimos/robot/manipulators/test_blueprints.py -q

Current result: 632 passed, 12 deselected.

The suite covers whole-plan mapping, subset trajectories, multi-arm atomic dispatch, execute/cancel serialization, typed coordinator outcomes, start-state rejection, one-task enforcement, module lifecycle cleanup, and updated manipulator blueprints.

Additional validation:

• 12 Drake/self-hosted manipulation integration tests passed.
• 2 self-hosted-large single/dual-arm blueprint and RPC tests passed.
• Generated blueprint registry validation passed.
• Targeted mypy passed for the production execution, manipulation, RPC-shell, and blueprint changes.

AI assistance

OpenAI Codex with GPT-5 provided substantial assistance with design exploration, implementation, tests, documentation, and review-feedback changes under human direction. The author reviewed and approved the design decisions interactively.

Checklist

• I have read and approved the CLA.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Jul 25, 2026, 7:52 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 94.89655% with 37 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/manipulation/manipulation_module.py	75.36%	12 Missing and 5 partials ⚠️
dimos/manipulation/execution_manager.py	94.59%	3 Missing and 3 partials ⚠️
dimos/control/coordinator.py	86.20%	2 Missing and 2 partials ⚠️
...mos/e2e_tests/test_manipulation_planning_groups.py	75.00%	4 Missing ⚠️
dimos/manipulation/test_execution_manager.py	97.14%	1 Missing and 3 partials ⚠️
...s/control/tasks/trajectory_task/trajectory_task.py	96.36%	2 Missing ⚠️

@@            Coverage Diff             @@
##             main    #3183      +/-   ##
==========================================
+ Coverage   74.90%   74.95%   +0.05%     
==========================================
  Files        1114     1115       +1     
  Lines      106086   105864     -222     
  Branches     9665     9625      -40     
==========================================
- Hits        79461    79354     -107     
+ Misses      23816    23719      -97     
+ Partials     2809     2791      -18     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	68.57% <91.58%> (+0.06%)	⬆️
OS-ubuntu-latest	70.58% <91.58%> (+0.06%)	⬆️
Py-3.10	70.57% <91.58%> (+0.06%)	⬆️
Py-3.11	70.57% <91.58%> (+0.06%)	⬆️
Py-3.12	70.58% <91.58%> (+0.06%)	⬆️
Py-3.13	70.58% <91.58%> (+0.06%)	⬆️
Py-3.14	70.58% <91.58%> (+0.06%)	⬆️
Py-3.14t	70.58% <91.58%> (+0.05%)	⬆️
SelfHosted-Large	29.20% <31.90%> (-0.13%)	⬇️
SelfHosted-Linux	35.95% <39.50%> (+0.02%)	⬆️
SelfHosted-macOS	35.05% <39.50%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/control/test_control.py	95.89% <100.00%> (+0.63%)	⬆️
dimos/manipulation/conftest.py	100.00% <100.00%> (ø)
dimos/manipulation/planning/spec/config.py	96.15% <ø> (-0.08%)	⬇️
...anipulation/test_generated_plan_materialization.py	100.00% <100.00%> (ø)
dimos/manipulation/test_manipulation_module.py	100.00% <100.00%> (ø)
.../manipulation/test_manipulation_monitor_preview.py	98.44% <100.00%> (-0.01%)	⬇️
dimos/manipulation/test_manipulation_unit.py	100.00% <100.00%> (ø)
dimos/manipulation/test_plan_execution.py	100.00% <100.00%> (ø)
dimos/manipulation/test_planning_factory.py	97.91% <ø> (ø)
dimos/manipulation/visualization/types.py	100.00% <ø> (ø)
... and 22 more

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 25, 2026, 7:51 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[TomCC7]

@mustafab0 I'll leave this pr for your review, if you think it's good to go can just enable merge