[Cyberkona]

Summary

This PR adds ARX ONE (two ARX X5 arms, three RealSense D405 cameras) as a real-robot integration, and is meant as a template for other robots. Real-robot behavior that is not specific to this robot goes into the shared layers as options. Simulation and real robots run the same tools and choose a mode:

• Execution mode (--execution-mode): parallel (default, unchanged) or replanning. In replanning, each world-mutating result is read before the next world-mutating call. A failed action cancels the queued plan, and new actions wait for a confirmed stop and a fresh observation.
• Motion mode (environment metadata motion_execution): stepwise (default, unchanged) or wholepath. In wholepath, a move is one preflighted path, and gripper-only actions hold every joint at its measured angle for steps control periods.
• Environment-declared tool settings: finish statuses, whole motion profiles, measured 0-1 gripper-opening checks, and stop confirmation from receipts.

An environment that declares nothing keeps main's tool schemas, prompts and scheduling. The integration contains no model-facing tool code; it composes the shared direct tool profile.

This supersedes #28, which ported an earlier version of this work. The commits are rebuilt on the current main as independent features.

Commits

1. feat(tools): environment-declared finish statuses, motion profiles and opening checks. finish_statuses, motion_profiles and normalized_opening_tolerance in the environment metadata.
2. feat(execution): the replanning execution mode beside parallel.
   • ParallelToolExecutor gets small extension points.
   • execution/replanning.py adds the mode, and create_executor() selects it.
   • --execution-mode and IntegrationSpec.execution_mode choose it.
   • ToolOutput.action (ActionOutcome) reports what an action did; it is never serialized.
   • physical_hardware requires receipts to confirm a stop.
   • Job controls return cancellation receipts.
3. feat(tools): the wholepath motion mode. PathCommand, an optional backend step_path, preflighted paths with reachable_prefix, and joint holds for gripper-only actions.
4. feat(arx): the ARX ONE integration. Body device process, environment adapter, perception, offline tools and deployment templates. It declares replanning. Every episode confirms the arms are idle and takes the control lease; there is no read-only episode mode, and read-only work uses the offline capture and calibration tools.
5. build(arx): packaging. pyproject.toml and MANIFEST.in include the native sources, release_contents.py accepts them, and sdk_release.py validates the arx_one config.

Outside the integration (main code)

19 code files, plus packaging and docs. ✎ modified, ＋ added.

uni_robot_agent/
├── cli.py                       ✎ --execution-mode {parallel,replanning}
├── config.py                    ✎ execution_mode
├── session.py                   ✎ create the executor for the mode
├── integrations/base.py         ✎ IntegrationSpec.execution_mode (default "parallel")
├── execution/
│   ├── __init__.py              ✎ EXECUTION_MODES, create_executor
│   ├── parallel.py              ✎ extension points; scheduling unchanged
│   ├── replanning.py            ＋ replanning mode
│   └── scheduler.py             ✎ replan_observation / ends_episode facts, cancel_pending
├── services/environment/
│   ├── contracts.py             ✎ PathCommand
│   ├── backend.py               ✎ optional step_path
│   └── primitive.py             ✎ PathCommand dispatch
└── tools/
    ├── toolkit.py               ✎ ActionOutcome, model view kept after result transforms
    ├── jobs.py                  ✎ cancellation receipts
    ├── episode.py               ✎ finish statuses
    ├── scene/provider.py        ✎ capture_scene is a replan observation
    └── gripper/
        ├── contracts.py         ✎ motion profiles
        ├── opening.py           ✎ normalized opening tracker
        ├── motion.py            ✎ wholepath mode
        └── provider.py          ✎ mode-aware descriptions, ActionOutcome from receipts

pyproject.toml  MANIFEST.in  README.md  CHANGELOG.md
scripts/validation/release_contents.py  scripts/validation/sdk_release.py
docs/  architecture.md  development.md  integrations.md  running.md  services.md

Setting	Where it is chosen	Default
Execution mode	--execution-mode, else IntegrationSpec.execution_mode	parallel
Motion mode	environment metadata motion_execution	stepwise
Finish statuses	environment metadata finish_statuses	["success"]
Motion profiles	environment metadata motion_profiles	shared standard / approach / precision
Gripper opening check	gripper_opening_models (metric) or normalized_opening_tolerance (0-1)	no check
Stop confirmation	physical_hardware + receipt diagnostics.stop.status / execution_outcome	a simulation counts as stopped

Inside the integration (uni_robot_agent/integrations/arx_one/, 172 files)

Directories follow where and when code runs. body/ is the device process, environment/ and perception/ serve an episode, and offline/ runs outside episodes.

arx_one/                          172
├── __init__.py config.py session.py prompt.py operator_cli.py README.md DEPLOYMENT.md
├── environment/                    9   episode over the Body RPC: admission, control lease, step_path, observations
├── perception/                    13   snapshots, RGB-D geometry, extrinsics, depth completion
├── offline/                       17   outside episodes; never imported by an episode
│   ├── fleet/                      7   site manifest, Fleet client, fleet-wide stop confirmation
│   ├── capture/                    4   read-only observation capture and archive inspection
│   └── calibration/                5   eye-to-hand and eye-in-hand calibration and verification
├── deploy/                        11   configuration templates and launch scripts
└── body/                         114   device process
    ├── core/                      19   generic: RPC, leases, operations, quarantine, arm/camera contracts
    ├── host/                      10   generic: build, install, check and serve Bodies
    └── drivers/                   82   fake/ (minimal template), realsense/, arx_x5/ (incl. vendor ROS controllers)

• To add a robot, reuse body/core and body/host, and copy drivers/fake/ for each device kind.
• The robot's shape (arms, joints, cameras) comes from environment.json.
• Values tuned for the X5 are marked "Robot-specific" in environment/adapter.py. The README section "Adapting to another robot" lists them.
• Dependencies point one way: body/ imports no agent-side code, and an episode never imports offline/.
• The prompt stays in the integration (prompt.py).

Notes for review

• --execution-mode returns with parallel and replanning only; the former serial value is not accepted. It is separate from --tool-return-mode and --resource-scheduling, which still configure scheduling inside the parallel executor. An internal test that asserts the option is absent (test_runtime_init) needs updating.
• Known issue: Hybrid under replanning. actor_act reports no ActionOutcome, so a failed actor_act counts as unknown execution with an unconfirmed stop: queued actions are cancelled and world-mutating tools stay refused for the rest of the episode, in simulation too. Only the hybrid tool profile combined with replanning is affected; direct and parallel are not, and ARX ONE uses direct. This needs a follow-up that fills ActionOutcome from the actor's execution summary.
• Commit 4 alone lacks the packaging rules; commit 5 adds them. Every earlier commit builds and imports on its own.

Validation

• Each commit was checked out on its own: it compiles and imports, and the relevant offline tests pass. This repository ignores tests/, so the tests come from our internal suite. Commits 4 and 5 each pass 1064 ARX ONE, execution and gripper tests.
• The CPython 3.12-only ARX ONE tests pass on 3.12 (64 passed, with the admission and tool tests).
• The default tool specs are byte-identical to main at every commit.
• scripts/validation/tool_composition.py: 8/8.
• scripts/validation/release_contents.py accepts the built sdist and wheel.
• The public content scan finds no credentials or machine-specific paths.
• The remaining full-suite failures were checked one by one. None of them comes from these commits.