This migration from Forge 1.x / Dora 0.4.x requires coordinated deployment. Align the Forge packages, Dora CLI/coordinator/daemon, this node and its peer nodes before connecting a dataflow; replacing only one node in a Forge 1.x deployment is unsupported. Rebuild and redeploy executable artifacts with the matching environment. Keep stable/1.x for deployments that still use the previous stack.
The validated Python baseline is forge-msgs==2.1.0, Pillow==13.0.0, forge-common==2.1.0, the applicable forge-robot / forge-policy / forge-kinematics / forge-tool packages at 2.0.0, and dora-rs==1.0.1. Respect this repository's Python and SDK platform requirements. Forge package families have independent versions. Rust nodes retain the published forge_msgs crate 2.0.0 with Dora 1.0.1; Python Msgs 2.1.0 does not require a nonexistent Rust 2.1.0 release. The forge_msgs.v1 message namespace remains unchanged.
This notice describes the deployment break from the previous stack; it does not declare hardware, real-model or sustained-run acceptance complete. See this round's verification report for actual tests and outstanding gates.
Standalone Forge Tool policy node that exposes simulation-scene control for the
robot-control-sim skill: a robot metadata query and a scene reset
action with deferred re-home on the sim.control endpoint.
| Item | Current implementation |
|---|---|
| Production Nodes | 1: sim_control_policy; source command forge-sim-control-policy, packaged entrypoint dist/sim_control_policy |
| Tool integration | Dora ToolMessage provider; caller-facing access through Gateway |
| Direct HTTP Tool API | 0; this Node does not listen on HTTP; Gateway owns the invocation URL |
| Endpoints | 1: sim.control |
| Operations | 2: get_robot_info (Query), reset (Action, not cancellable, status supported; each has maximum concurrency 1) |
| Gateway Tools | Deployment-defined in tools.specs; robot-control-sim binds 2 Tools to this Endpoint, listed below |
| Tool ID (robot-control-sim configuration) | Endpoint / operation | Provider Node |
|---|---|---|
sim.get_robot_info |
sim.control / get_robot_info |
sim_control_policy |
sim.reset |
sim.control / reset |
sim_control_policy |
reset resets the scene through sim_command. With re-home configured, this Node is also a Tool caller:
it invokes Gateway-configured Motion/Gripper Tools over tool_request/tool_response.
Those operations belong to other providers and are excluded from this repository's Endpoint/operation counts.
ToolSpec implementation_id is a deployment binding identifier and may differ from the package or Node name; use the actual profile.
Complete contract: TOOL_CONTRACTS.md. Descriptor: info.py. Reset orchestration: control.py.
Compatibility: current dependency declarations are dora-rs>=1.0.1,<2, forge-msgs>=2.0.0,<3. See pyproject.toml and uv.lock. The Tool protocol implementation comes from the official forge-tool[dora] distribution. These declarations do not guarantee cross-version interoperability; also check the build revision and Skill lock when using artifacts.
Changes to Node entrypoints, Endpoints or Tool APIs must update this section and the associated configuration/contracts. Follow the Node README contract.
| tool_id | implementation_id | endpoint_id | operation | semantics |
|---|---|---|---|---|
sim.get_robot_info |
sim-control-policy |
sim.control |
get_robot_info |
query |
sim.reset |
sim-control-policy |
sim.control |
reset |
action |
Full request/response shapes, idempotency, and error codes are specified in
TOOL_CONTRACTS.md.
The move-arm-by-ee runtime chain (gateway → motion policies → motion server →
controllers → mujoco) already moves the simulated arm by joint values or by EEF
pose. Two things were missing for a simulation-control skill, and both live here
so that no other runtime node needs to change:
get_robot_info(query) — returns the validated robot descriptor (joint names/order, dof, per-joint kind/limits, EEF site, initial pose) so agents can discover any bundled or user-supplied robot at runtime instead of parsing SKILL.md.reset(action) — resets the MuJoCo scene (reset_sceneoversim_command) and re-homes the robot to the descriptor'sinitial_qpos. The re-home rides the gateway's public caller channel: after asettle_mswindow the node dispatches innermove_joints/set_openingTool invokes, aggregates their completion, and only then completes the outer invoke — so a terminalsim.resetresult means the scene and the robot are actually at the initial state (the JTC hold tick can no longer drag the arm back). When the profile has noreset:block the invoke completes immediately after the scene reset.
Robot variation is entirely declarative: the node only reads a robot.yaml
descriptor next to the robot's MJCF/URDF assets. Adding a robot never requires
code changes here.
# profiles/<profile>/sim_control_policy.yaml
robot_descriptor_path: ../../robots/piper/robot.yaml # relative to this file
# Optional re-home stage; omit for instant completion after the scene reset.
reset:
motion: # mandatory when reset is present
tool_id: sim.set_joint_positions
implementation_id: motion.integration
endpoint_id: motion.server
operation: move_joints
arguments:
group_name: piper_arm # plus velocity_scale / acceleration_scale
gripper: # optional; omit for arms without a Tool-driven gripper
tool_id: sim.set_gripper_opening
implementation_id: piper.gripper
endpoint_id: gripper.controller
operation: set_opening
timeout_ms: 15000 # re-home budget (default)
poll_interval_ms: 1000 # result-lookup cadence (default)
settle_ms: 500 # simulator propagation window before motion (default)See tests/ for the full schema (validated strictly; unknown keys are
rejected).
| input | purpose |
|---|---|
tool_in |
Tool envelopes from the gateway (invoke/registry) |
tool_response |
gateway replies/events for the inner re-home invokes |
joint_state |
mujoco/proprio_state; feeds sim.get_joint_state |
tick |
keeps the registration lease and re-home timers driven |
| output | purpose |
|---|---|
tool_out |
responses, lease registration/unregister envelopes |
tool_request |
inner Tool invokes on the gateway caller channel |
sim_command |
raw UTF-8 JSON {"command": "reset_scene"} to mujoco |
uv sync --frozen --all-groups
uv run pytest -q
uv run ruff check .
scripts/build_pyinstaller.sh # single-file executable -> dist/sim_control_policyThe forge_tool package is vendored under src/forge_tool/;
sim_control_policy_node/__init__.py prepends it to sys.path (defensively,
also under PyInstaller). Keep it byte-identical to the copy in the other policy
nodes.
Apache License 2.0 — see LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.
This branch prepares node version 2.0.0 for Dora 1.x, frozen to Dora 1.0.1 for migration validation. It uses the official Forge 2.x distributions; Common is at least 2.1.0. Regenerated locks and all executable entrypoints are part of the change.
Every change report must list repository, changes and test evidence, including per-node dora run records and a chained test containing adapter-forge-gateway. Unavailable hardware/model checks remain pending. Source PRs do not publish stable releases or synchronize GitLab; synchronization follows full acceptance.
ToolEndpoint implementations now come from forge-tool[dora]>=2.0.0,<3. The former repository-local Tool copy and private message imports are removed; messages use the public forge_msgs.ToolMessage.
Mandatory tag-first release rule: merge the version/lock change, create an annotated version tag on that reviewed commit, build that exact tag, validate the artifacts, then publish. Moving branch names, untagged commit IDs and replacement of published tags are not release inputs.
| Release line | Source | Node/package version | Runtime |
|---|---|---|---|
| Forge 1.x | stable/1.x |
1.x, tag v1.X.Y |
Forge 1.x / Dora 0.4.x |
| Forge 2.x | master |
2.x, tag v2.X.Y |
Forge 2.x / Dora 1.x |
Legacy normalization: nodes previously at 0.x on stable/1.x release as 1.0.0, retaining Forge 1.x / Dora 0.4.x dependencies and runtime behavior. Existing 1.x package versions are retained. Node/package majors now follow the Forge compatibility line; a 0.x tag is rejected.
Run Build versioned release from master for either line. First merge the version/lock changes into the selected source branch, then create an unused annotated tag on that reviewed commit. The tag must match package metadata. Never move existing tags or reuse a published version. Dispatch uses the workflow's reviewed tooling with the exact tagged source, so legacy tags need not contain the new release helper.
# Replace with an existing, reviewed and unpublished tag matching source metadata.
TAG=v1.X.Y
gh workflow run release.yml --ref master -f release_line=1.x -f tag="$TAG"
TAG=v2.X.Y
gh workflow run release.yml --ref master -f release_line=2.x -f tag="$TAG"The workflow verifies tag type, source commit, branch ancestry, source version and locked Forge/Dora compatibility. It builds source archives and wheel/sdist where supported, checks Python distribution metadata and SHA-256, and creates or attaches to a draft GitHub Release. Published releases/assets are not overwritten; review all build results and acceptance evidence before publishing. This workflow does not publish node packages to PyPI.
Set build_binaries=true to call the existing Ubuntu 20.04 binary workflow; its existing architecture, CLI and archive checks remain in force. You can also run build-ubuntu20.yml directly with ref, version and release_line; ref must be an annotated tag, not a moving branch. Binary artifacts are attached only after all selected jobs succeed.
The source archive preserves the tagged tree; external SDKs/submodules, model downloads and site configuration remain separate prerequisites. A dependency or SDK build failure is not successful release acceptance. Build success does not establish single-node or Gateway-chain dora run, hardware, real-model, sustained-run or rollback acceptance. Every acceptance chain must include adapter-forge-gateway from the same compatibility line. Forge 2.x is a breaking change: align Forge libraries, node versions and Dora across the entire deployment; keep 1.x on its maintenance branch.