feat: add stateful control task API

[TomCC7]

Contribution path

• Builds on feat: extract manipulation plan execution manager #3183, now merged into main

Problem

Control tasks were originally tick-driven and effectively stateless: compute() received the complete CoordinatorState needed to produce the next command.

Tasks can now expose RPC commands that run outside compute(). For example, JointTrajectoryTask.execute() must validate a trajectory against the latest joint state, but it receives no state argument. The previous workaround added trajectory-specific methods to ControlCoordinator, making the generic coordinator depend on an optional task and requiring another wrapper for every future stateful task command.

Tasks need a narrow way to fetch the coordinator's latest observation during an RPC command without taking ownership of state collection.

Solution

• Cache the latest complete, immutable CoordinatorState before task filtering.
• Give registered BaseControlTask instances transparent access through self.context.get_state().
• Keep ControlTaskContext stateless: it exposes a function that reads coordinator-owned state and performs no hardware read or freshness check.
• Tie context access to task registration. Stop/start preserves access; removal or coordinator deletion revokes it; access outside registration raises RuntimeError.
• Preserve structural ControlTask support without requiring context.
• Route task RPCs through generic task_invoke(task_name, method, kwargs).
• Treat TASK_EXPOSES as a strict allowlist, validate arguments, and propagate task results and exceptions unchanged.
• Give JointTrajectoryTask the fixed unique name joint_trajectory, move start-state validation into the task, and remove trajectory-specific coordinator RPCs and state injection.
• Migrate manipulation execution, coordinator clients, blueprints, documentation, and tests to the generic task-command API.

Test organization

• Stateful task and registration contracts live in dimos/control/test_task_context.py.
• Manipulation execution behavior lives in test_manipulation_unit.py; the redundant test_plan_execution.py suite is removed.
• Real Drake coverage is named test_manipulation_drake_integration.py and keeps one plan-to-dispatch integration boundary instead of duplicating mocked unit behavior.

Validation

uv run pytest -q dimos/control dimos/manipulation
uv run mypy \
  dimos/control/task.py \
  dimos/control/coordinator.py \
  dimos/manipulation/manipulation_module.py
uv run ruff check dimos/control dimos/manipulation
git diff --check

Local result after rebasing onto main: 648 passed, 9 deselected across
dimos/control and dimos/manipulation; mypy passed 925 source files.

AI assistance

Codex with GPT-5 helped design, implement, migrate, and test this change. The author reviewed the design decisions interactively.

Checklist

• I have read and approved the CLA.

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
dimos/e2e_tests/test_control_coordinator.py	9.09%	20 Missing ⚠️
dimos/control/test_task_context.py	94.38%	10 Missing and 1 partial ⚠️
...anipulation/test_manipulation_drake_integration.py	10.00%	9 Missing ⚠️
dimos/manipulation/test_execution_manager.py	84.78%	4 Missing and 3 partials ⚠️
dimos/manipulation/conftest.py	42.85%	2 Missing and 2 partials ⚠️
dimos/manipulation/test_manipulation_unit.py	96.22%	1 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##             main    #3238      +/-   ##
==========================================
- Coverage   75.20%   74.99%   -0.21%     
==========================================
  Files        1128     1130       +2     
  Lines      107954   108359     +405     
  Branches     9751     9761      +10     
==========================================
+ Hits        81188    81266      +78     
- Misses      23955    24355     +400     
+ Partials     2811     2738      -73     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	68.92% <89.07%> (+0.06%)	⬆️
OS-ubuntu-latest	70.98% <89.07%> (+0.06%)	⬆️
Py-3.10	?
Py-3.11	70.98% <89.07%> (+0.06%)	⬆️
Py-3.12	70.97% <89.07%> (+0.06%)	⬆️
Py-3.13	?
Py-3.14	70.98% <89.07%> (+0.06%)	⬆️
Py-3.14t	?
SelfHosted-macOS	?

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

Files with missing lines	Coverage Δ
dimos/control/blueprints/mobile.py	100.00% <ø> (ø)
dimos/control/coordinator.py	87.28% <100.00%> (+5.25%)	⬆️
dimos/control/task.py	88.79% <100.00%> (+8.33%)	⬆️
.../tasks/g1_groot_wbc_task/test_g1_groot_wbc_task.py	100.00% <100.00%> (ø)
...s/control/tasks/trajectory_task/trajectory_task.py	92.39% <100.00%> (+2.44%)	⬆️
dimos/control/test_control.py	97.86% <100.00%> (+1.97%)	⬆️
dimos/control/test_coordinator_commands.py	97.02% <100.00%> (-1.09%)	⬇️
dimos/control/test_coordinator_routing.py	99.41% <ø> (ø)
dimos/control/tick_loop.py	79.72% <100.00%> (+9.63%)	⬆️
...mos/e2e_tests/test_manipulation_planning_groups.py	88.39% <ø> (+5.48%)	⬆️
... and 14 more

... and 24 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	🟢 Ready	View Preview	Jul 30, 2026, 12:53 AM

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