Every ToolSurface is plain files. Each tool is one directory holding the code it runs and what the model is shown for it, written exactly as delivered; the surface selects tools and may carry its own prompt and its own tool files.
ora/agent/toolkit/tools/<name>/
tool.py run(api, args); ora/agent/toolkit/registry.py finds it by name
description.json ora.toolkit-tool.v1: description, inputSchema, resultSchema
ora/policy/tool_surfaces/<profile_id>/
surface.json ora.toolkit-surface.v1: tool order, roles, capabilities,
view config, required grants, receipt delivery,
tool_descriptions
prompt.md the surface prompt (may be empty)
<file>.json ora.toolkit-tool.v1 for one tool on this surface
A surface names a tool that has both files, or one whose description it keeps
itself. tool_descriptions maps a tool to a description file beside the
manifest, which replaces that tool's shared description.json on this surface
alone. Such a file may leave out resultSchema: the tool's own result schema
then applies, and the resolved surface records the file it came from as
component result:<name>. "resultSchema": null says the tool has no public
result schema (the robot_runtime_v2 and Synthetic Native tools). A tool name
is snake case, or dotted segments of it (robot_runtime_v2's
observation.dump_state). A tool_descriptions entry is a path string: an
inline {ref, sha256} pin is refused.
Surfaces written out from layered manifests
Until 2026-11-03 most surfaces were layered manifests: a base catalog, ordered
description, schema and result layers, and capability binders that rewrote the
composed text. Each was written out in this form in place, by a tool removed
with the layered resolver: the registered manifest kept its path and became the
surface file, with its profile id, revision, runtime, tool order, roles,
capabilities and view config, and a <tool>.json beside it holds exactly the
definition its layers and binders composed wherever that is not the tool's own
description.json. The path stayed because sealed plans, documents and the
embodiment descriptors' provenance name it; provenance.flattened_from is the
commit whose layered manifest was written out. Only the component list, the
manifest and composition hashes and the provenance changed;
compare-model-visible was the same in every cell. No binder runs: the text is
in the files. dry_run stays the resolver's to add to the moving tools.
Written out: yam_direct_v1 (YAM free play with --no-perception; its
successor yam_perception_v1, YAM's default, was authored as files too),
robolab_direct_v1,
robocasa_mobile_direct_v1 (robocasa_mobile_v1/),
libero_placement_direct_overhead_v1 (explicit_motion_v3/),
robotwin_toolchain_b2_closed_noservo_v2 (toolchain_b2_noservo_v1/),
robot_runtime_v2, native_atomic_causal_v1 and local_atomic_cpu_v1. The
last three also declared toolkit_only_v1 then, which the host had added to
them at run time before; their plans name it, nothing the model reads changed.
A sealed plan keeps the definitions it was shown and the component paths it
read; evaluation and replay read neither from the tree.
Receipts in the tool result
Each action tool's description.json describes its native result: the tool
returns its completed execution receipt and remaining_budget, and the
current camera images come with the next observation. A tool's own images
cannot ride in a tool message: a result names them, and they are delivered in
the user message right after the batch's results, before the next model call.
One description serves every surface; a surface that delivers receipts another
way says so at the surface level.
The current one: robodojo_placement_toolkit_v6
robodojo_placement_toolkit_v6 is v5 without the official check, RoboDojo's
default since 2026-11-02 (baseline robodojo_toolkit_v7, bundle toolkit_v7,
context profile robodojo_public_explicit_v7 with boundary-v3.md). The simulator's official predicate is
all a success needs: it ends the episode, and no tool reads it.
- Nineteen tools: no
check_task, norequired_grants, nofaithful_check_taskcapability, so the Runtime writes nopolicy-task-check.json. finish_episodeisfinish_episode.jsonon this surface:give_up, andaborton recorded infrastructure evidence. The model cannot declare success.- The round ends at the official boundary with no terminal turn, so the model gets no message about the verdict.
prompt.mdis v5's without the rule on spending native actions, because no native-action count ends a fresh RoboDojo run.
Everything else, tool by tool, is v5, below. v5, baseline robodojo_toolkit_v6
and bundle toolkit_v6 stay registered so the plans sealed on them resolve.
robodojo_placement_toolkit_v5
robodojo_placement_toolkit_v5 is robodojo_placement_toolkit_v3's tool set
plus return_home, with the check_task grant and tool_output receipts,
written out once per tool. v3, the layered legacy-visible surface it was
written from, was retired on 2026-10-31; the comparisons with v3 below describe
v3 as it was. Its roles, capabilities and view config are v3's
under toolkit_receipt_delivery: tool_output; the action tools' descriptions
are rewritten for the receipt they return instead of v3's "explicitly selects
tool_output" addendum. A RunSpec on it resolves
toolkit_receipt_delivery: tool_output without stating it.
Where it departs from v3 (all recorded in
tests/ora/agent/composition/surface/test_toolkit_surface.py):
- Moves run as joint trajectories:
move_pose,move_to,rotate_wrist,rotate_pitchand the arm stages ofgrasp_executeeach run as one screened, smooth joint trajectory instead of the released primitives. - New optional inputs, each defaulting to v3's behavior:
speed(fast|normal|careful),slow_approaching,expect_contactandexact_orientationonmove_pose;expect_contactonmove_to;expect_contactandexact_orientationonrotate_wristandrotate_pitch. v3's inputs stay accepted unchanged.speedsets only the pace: the interaction label picks the route at every speed (lib.motion_plan.route).expect_contact: trueis the one straight line past 50 mm / 15 degrees, refused rather than replaced by another path. A controlled descent iscontact_approachor a planned path. - Where the shared planner runs, the straight part of a
contact_approachor anexpect_contactmove is checked before it runs: the fingers may touch, and any link behind them that would go into what the cameras see refuses the move (contact_path_blocked). Aprecisionline inside the local envelope has no such check. move_pose's result gains amotionfield: how the trajectory ran (route, speed, planned and executed knots, stop, settle, per-arm errors,joint6(per arm, the wrist roll's start, end, min, max, travel and least limit margin from the start joints through every planned knot), andbudget_limitedwhen its budget covered only part of the move). A budget cut never stops a joint-line bridge, or a joint-space move that turns joint 6 by 90 degrees or more, part way: the covered part ends before it, or the move is refused before anything moves (paced_motion_budgetwithunsplit_span) when it starts with one.recover_posetakesarmsinstead of v3'stargets: each named arm undoes its latest arm-moving tool call along that call's measured path, one per call.return_home {arms}lifts, then unwinds to the reset joints. Policy I/O has the recovery semantics.finish_episode'sgive_upadds theinsufficient_budgetcategory andreport_issuean optionalkind(defect|confusion); see Lifecycle.
Execution budgets differ from the released primitives' too. They are offline
implementation configuration in ora/agent/toolkit/tools/budgets.py:
every tool that moves the arm 250, what one joint trajectory may use, so a move
finishes unless the episode runs out; set_gripper 30, wait_ticks 20 and 810
for grasp_execute, whose three arm stages and two jaw commands each fit their
own limit; read-only and lifecycle tools spend 0. One call can spend 250 of the
episode, and its plan and dry run report what it will cost. The
model cannot supply native_action_budget, including zero, and the official
remaining allowance can reduce admission.
It was RoboDojo's default surface from 2026-10-30 to 2026-11-02. Naming it
resolves robodojo_toolkit_v6, the baseline the surface brings, with the
check_task grant the surface requires. That baseline uses the
toolkit_v6 bundle (planner policy-v6.md, core evidence-action-loop-v9.md,
this surface's prompt.md in the system channel) and the
context_keep_written scheme (keep-written context; context_keep_written_unaged_reasoning on 2026-11-04 and 05, before that context_rolling_tail_v2, append-only context, retired on 2026-11-05).
Code mode runs on it from prompt: v2 (see public interfaces).
robodojo_toolkit_v5 (the same surface with context_rolling_tail_v1 and no
surface prompt) was retired on 2026-10-31; sealed runs keep their recorded
definitions. Naming v5 brings its baseline and required grants:
{
"policy": {"tool_surface": {"profile": "robodojo_placement_toolkit_v5"}},
"record_toolkit_io": true,
"toolkit_grants": {"tools": ["check_task"], "state_keys": ["privileged.task_check"]}
}
Retired surfaces
robodojo_placement_toolkit_v4, the file-backed surface that delivered
receipts with the next observation (an action tool's own output was its
submitted confirmation, and a result_overrides file restored the
observation-delivery result schemas), and its baseline robodojo_toolkit_v4
were retired on 2026-10-31, together with the layered v1 and v3 surfaces. No
registered surface delivers receipts with the observation any more. Sealed runs
keep their recorded definitions; evaluation, trace verification and export do
not need the repository's copy.
In-place change (2026-10-28): v4 and v5 gained everything listed above
(return_home, the new optional inputs, the motion result field,
recover_pose {arms} and joint-trajectory moves) in place, with no revision
bump. A run sealed on either keeps the surface of its plan's commit (the plan
pins each file's sha256). These applied only to v4 and v5: the layered v2
keeps the released primitives, inputs and budgets. Later on 2026-10-30 RoboDojo's default
moved from robodojo_placement_closed_skills_v2 to v5 with
robodojo_toolkit_v6 (user direction); the closed-skills surface and the v4 baseline's RoboDojo
instance were retired on 2026-11-01.
toolkit_receipt_delivery may only restate a file-backed surface's own
delivery. Component overrides are refused: change the files instead.
Resolution
resolve_tool_surface reads the manifest (surface.json, or the manifest file a
written-out surface kept), then each listed tool's
description.json in order, through policy.lock (which covers
ora/agent/toolkit/tools/*/description.json besides ora/policy/). It checks each file's schema and name,
lints the input schemas, validates the tool-help contract when the surface
declares policy_tool_help_v1, and resolves the view config, tool roles and
effect profile. Nothing is composed or rewritten. The ResolvedToolSurface records one component per file
(tool:<name>, and surface_prompt), so a RunPlan pins every byte it used.
Grants are the surface's own: required_grants must equal the RunSpec's
toolkit_grants, and validate_grants applies its capability rules (a
toolkit_legacy_projection_v1 surface requires both check_task grants).
Surface prompt
prompt.md holds notes on the tool set as a whole. When it has text, the
baseline adds it as the last tool_manual layer, after the prompt bundle's
manual; when it is empty (as for v5), no layer is added and the prompt layers
are byte-identical to a surface without one.
Correction (2026-10-26): tool_manual is a manifest-only channel
(context_audit.py: not_delivered), so a surface prompt is pinned in the
plan but never delivered to the model. Earlier text here said it was
delivered. Delivering surface and context-scheme prompts through the system
channel is in progress (R0022 D4).
Changing a surface
A description belongs to its tool: editing tools/<name>/description.json
changes what every surface listing that tool shows. Sealed runs are unaffected
(their plan records the commit and each file's sha256). Keeping two versions
of one tool's description selectable side by side is not supported yet.
To change the tool set or the prompt, copy the surface directory to a new
profile id, edit the copy, register it in
ora/agent/composition/surface/profile_catalog.py and add a baseline if runs
should select it by baseline. After any change run ./scripts/ora lock and
compare what the model sees (scripts/dev/compare-model-visible, or a test
like the one above).
Resident services
Toolkits v5 and v6 bind their resident services the way every other surface does: the
ora.model-service-set-binding.v2 prerequisite names the plan's own surface in
each child's tool_surface, and preflight and the runtime both verify each
child against that surface. A child bound to another surface is refused.
Endpoint, instance/process, model, adapter and qualification checks run through
the unchanged service clients. There is no cross-profile reuse.
Until 2026-11-01 v5 declared resident_service_binding so that a service set
bound to robodojo_placement_closed_skills_v2 could serve it, and plans recorded
that as plan.json.service_binding_resolution. Both left with the closed-skills
surface. The field stays in plans already sealed and nothing reads it.
Branching on a surface
Runtime code asks the resolved surface for its capabilities
(toolkit_only_v1, toolkit_synchronous_execution_v1,
toolkit_legacy_projection_v1, faithful_check_task), never for its name, so a
new surface inherits exactly the behavior it declares.
ora/agent/composition/surface/toolkit_profiles.py only records the first toolkit
tool cohort and the default baseline of each RoboDojo toolkit surface. Every
registered surface declares toolkit_only_v1, and the host installs the toolkit
tools for exactly those (served).