Reference

Public interfaces

Import from the explicit ora subpackages. There are no flat compatibility re-exports or managed Codex/Claude Code adapters.

Operator and composition

Interface Owner Contract
ora ora.app.main (one parser, the command table COMMANDS, the grouped help), one ora.app module per command group Every command: ora.app.plan (validate, show, preview context, preflight), ora.app.runs (launch, retry, status, stop, watch, workspace), ora.app.evidence (evaluate, seal, revalidate, export, inspect), ora.app.report, ora.app.spec, ora.app.qualify, ora.app.suite, ora.app.dev (operator tools on their own parsers), ora.app.catalog, ora.app.providers, ora.app.services (command guide, command reference).
ora doctor ora.app.doctor Read-only Python/distribution, credential-presence, interpreter/asset, graphics-library and agent-core discovery (Node.js version, locked ora-pi packages, the selected core). Never prints key values or starts a simulator.
ora local, ora setup, ora doctor --env local ora.app.local, ora.app.local_setup, ora.app.setup Local CPU MuJoCo LIBERO: pinned setup, read-only readiness check, and the reduced ora_local_cpu_v1 composition on the shipped local-cpu host profile. Launch needs --confirm-launch.
ora interactive, ora attach, ora sessions ora.app.interactive, ora-pi/src/tui/ Without --spec (or with --ui pi): one run on the Pi agent core, launched through the normal resolve, preflight, lease and detached-Supervisor path with ORA_PI_TUI=1. The headless agent process serves Pi's InteractiveMode on a unix socket outside the run (announced in native/pi-tui.json, ora.pi-tui-endpoint.v1); ora attach relays one terminal to it, detaching leaves the run going and a restarted agent process is re-attached. Typed text steers through operator_control: file_inbox_v1; /stop stops at the next model-call boundary; Pi built-ins that would rewrite the episode, switch model or credentials, reload or upload are refused. The provider comes from a provider profile or the quickstart environment; credentials never reach Pi's own storage. ora sessions lists runs with a Pi session and exports one (Pi's HTML, or the session JSONL).
ora play ora.app.play, ora.orchestrator.episode.play, ora.orchestrator.play.scenes, ora-pi/src/play/, ora-pi/src/tui/ One free-play run (ora-play, episode_mode: "play") on the Pi core. Pi runs as a coding agent (its tools, commands, skills, context files, model registry) with ORA's robot tools; the scene comes from what the host has qualified and carries no task (--scene-set draws among ORA's own audited RoboTwin scenes, ora.environment.benchmarks.robotwin_play_scenes, qualified by ora play audit --env robotwin). Typed text is the next instruction, Esc sends stop_instruction, and /reset and /quit are the session controls (guide).
ora interactive --spec ora.app.backend (python -m ora.app.backend, started by ora-pi/src/watch/), ora.app.task_catalog, ora-pi/src/watch/ Task picker over prepared Native RunSpecs; JSON-lines requests prompt, steer, follow_up, abort; steering through operator_control: file_inbox_v1; end follows the Supervisor's landing.
World view, ora-remote ora.app.world, ora.orchestrator.world_view, ora.app.remote, ora.app.remote_session Loopback, read-only browser companion bound to the run's original execution capture, served beside the task picker, ora watch and an attached Pi terminal (TerminalWorldFeed, its state relayed to the TUI); laptop-side SSH launcher for play, interactive, attach and watch that forwards it, runs the remote TUI on this terminal and re-attaches the same command to the run it left going; with web or --web it forwards ora web's gateway socket instead and hands over the launch token in a 0600 file on a first SSH command (one control master).
Pi RPC, ora-rpc-attach ora-pi/src/rpc/, ora-pi/bin/ora-rpc-attach The agent core of a Pi-core run (with ORA_PI_TUI=1, or alone with ORA_PI_RPC=1) serves Pi 1.3.0's RPC protocol on a 0600 unix socket outside the run (announced in native/pi-rpc.json, ora.pi-rpc-endpoint.v1): Pi's commands and events, LF-delimited JSON. One controller, any number of observers (observers only read; ora_attach {role} from the stand-in, ora_get_role, ora_take_control). ORA adds ora_get_run (the run ID, its mode, the commands that mode refuses with their reasons, free play's state, playMessages: the operator's messages with their state queued or delivered, joined, next (held by the Supervisor for the next instruction), instruction and step, and playEndings: the ora.play-instruction.v1 records of the instructions that ended with at, when the agent process heard of it), ora_get_frames {step?} (read-only, observers too: the run's recorded motion, motion: {cameras, fps, steps: {step: frames}}, and operator view, operatorView: {camera, width, height, steps, latest}; with step, that step's motion frames by camera URL /ora/capture/<frame>.png and its operator view /ora/operator-view/<step>.png; an action belongs to the observation step it was proposed at), ora_play_control {control} (free play only: stop_instruction, reset or quit, recorded as the terminal's own Esc, /reset and /quit), ora_play_queue {message} (free play only: a queued_instruction, as the terminal's Alt+Enter: held by the Supervisor until the running instruction ends, then the next one; a follow-up, Pi's own queue key, is one too while the agent streams), the event ora_play_state (each ora.play-state.v1 announcement of the free-play Supervisor, display only: instruction, message_queued, message_queued_next, message_delivered, action_started, action_finished, instruction_finished, control, scene, scene_ended, awaiting_instruction, ended; with atMs, when the agent process received it: the record carries no clock), the event ora_play_message (one operator message queued or delivered) and the event ora_model_call (free play, display only, never in the model's context or the trace: one model call's {id, step, startedMs, firstTokenMs, endedMs, outputTokens, inputTokens, cachedInputTokens, stopReason} on the agent process's clock, the first token being the reply's first text, thinking or tool-call content; ora_get_run's perf holds the record so far: calls, observations as [step, ms] and actions {step, actionId, startedMs, finishedMs, durationS}); standard Pi clients ignore them. An episode refuses model, reasoning, compaction, retry, shell, new/switched/forked/cloned/renamed sessions and host-side export in the agent process; free play opens Pi's commands but export. Prompts, steers and follow-ups pass ORA's input hook (operator messages in an episode, where a follow-up is delivered as a steer: one kind of operator message, before the next model call). toolResult and observation messages (an episode's ora.observation, free play's ora.play_observation) carry ORA's camera images (ImageContent, details.ora = {step, toolCallId, camera, artifact, images}); get_messages inlines the latest three steps, earlier ones by /ora/artifacts/<file> URL. Extension notifications go to every client and to the attached TUI (whose InteractiveMode builds the session's uiContext through the RPC host's composite); a dialog goes to the client whose prompt raised it, else to the TUI, else to the controller. ora-rpc-attach stands in for pi --mode rpc (Pi's RpcClient cliPath): it relays stdio to the run named by --ora-run/ORA_RPC_RUN or by its --session file, reports that --session path as sessionFile, refuses a run that is not live and never starts Pi.
ora web ora.app.web, ora.app.web_gateway, ora-pi/web/ A live run in the browser: ORA's own page (React, seeded from Watercol/pi-web-ui, MIT; built by ora web setup, which records the digest of its sources in dist/ora-build.json, and refused when built from other sources) and its Node server (ora-pi/web/server), one controlling Pi RPC client of the run through ora-rpc-attach. The conversation and the robot's cameras on one screen: live frames from the run's world view, the conversation drawn compact by default (one line per thought, Thought for N s from the call's durationMs, one line per tool call with its name and arguments, one per observation; a click opens it) or detailed (each observation with its images, each tool call as a card with its step's image), with Expand all thinking, both remembered by the browser (ora.web.display) or chosen by the link (view=, thinking=expanded); a selected call's vision_ground/vision_segment boxes and mark_point points drawn over the step's image, a step timeline with replay. Messages are Pi's prompt, steer or follow-up, and in free play a queued instruction (ora_play_queue, held by the Supervisor and listed above the box until it starts); dialogs are answered with Pi's extension_ui_response; free play's controls are ora_play_control, its phase is the Supervisor's (ora_play_state); a message sent while an instruction runs is shown joined to it, queued until the agent reads it and then with the step it read it at, the agent's next words as its answer, and a marker where each instruction ended (ora.play_message, playMessages, playEndings). The header and the composer say what the agent does now with its seconds (thinking, writing, a tool, the robot moving), from the web server's activity; in free play a speed line at the camera panel's foot (ora_model_call, perf; on a real cell the gateway's /ora/cell answers: each motion question answered lately with created_unix_s when the gateway saw it waiting, answered_unix_s and by) opens to each model call's tok/s and TTFT, each loop between robot actions broken into model thinking, tools, the approval wait, planning and motion and the next observation, and what the median loop needs to meet a target the browser remembers (ora.web.loopTarget); the timeline shows each step's thinking and moving time. The camera panel plays the robot's recorded motion (ora_get_frames: the action executing now as it is recorded, the newest one after it, a selected step's with a scrubber) and shows the environment's operator view as the main picture when it has one, the robot's cameras as the secondary picture; the picture is one box fitted to the panel in the shape of the run's operator camera (--camera-aspect: a replay's from its capture's sharpest operator camera, else its operator views, else 4:3; a live page's from its first operator view, then kept; a 16:9 one widens the camera column to 3fr against the conversation's 2fr), every image drawn whole inside it (contain), the bars around it of fixed height and the motion bar and a call's image strip laid over it, so no image's source or size moves it. English or Chinese, from the browser's language unless chosen in the header (remembered in the browser). The page uses the shared minimal light template. The page offers only what the run's mode allows (ora_get_run's refusals; an episode shows no model, reasoning, compaction, session or rename controls, and the agent process refuses them anyway); there is no shell, file, directory or working-directory route. The gateway in front: a one-time launch token exchanged for an HttpOnly SameSite=Strict cookie, loopback Host, same-origin state changes, only the page's routes, the run's stored images, its recorded motion frames (native/execution-capture/frames/) and operator views (native/operator-view/) by exact file name, never through a link, and its world view. --socket (for ssh -L) or 127.0.0.1; a run that is not live is refused.
ora replay ora.app.replay, ora.app.replay_export, ora-pi/web/server/replay.ts, ora-pi/web/src/lib/replay.ts A finished run on ora web's page, rebuilt read-only from its evidence: GET /api/replay (ora.web-replay.v1: the page's own events, each at the moment it happened, from Pi's session, events.jsonl and agent-events.jsonl; the execution capture's frames and the operator views with their times; the run's actions and instructions; notes on what the evidence does not hold) is the web server's only route (ORA_WEB_REPLAY=1; every other /api route answers 410) and the gateway's (replay=True: the page, /api/replay, the run's stored images, motion frames and operator views; no world view, no Pi RPC). The page applies the events up to its clock with the live page's own reducer, at two rates (lib/replay.ts buildTimeline): the waiting at speed (16× by default) and each action's motion (submission to receipt plus settling frames) by its capture frames' simulated time at motion speed (1× by default, never shorter than at speed; same: one speed throughout), showing only captured frames, each held until the next; `?replay=1&speed=S&motion=X
ora run --env synthetic ora.app.quickstart; its RunSpec ora.orchestrator.spec.quickstart Bounded native_api demonstration through normal launch gates on the Pi agent core; waits for completed, sealed evidence. Its model comes from the ORA_* variables, or with --provider-profile ID from that Provider profile (quickstart.profile_policy: the base-URL variable defaults to the profile's endpoint; a missing key or another endpoint is refused before preflight).
ORA_AGENT_CORE, --agent-core (hidden) ora.orchestrator.episode.agent_core pi, the only agent core, or unset; native, the removed Python core, is refused with the reason. See agent core.
ora setup --env libero|robotwin|robodojo|perception ora.app.gpu_setup, ora.app.gpu_recipes, ora.app.env_file Idempotent single-GPU installation under a prefix outside the checkout: cu128 Torch in every simulator environment, CuRobo built for the GPU's compute capability, SAM3 from ModelScope against its pinned SHA-256, the setup-robodojo stages through graphics-compat. Step markers <prefix>/manifests/ora-setup/<step>.json (ora.ora-setup-step.v1) record each recipe digest. Writes only its own non-credential .env keys; starts no simulator, service or Provider call.
ora run --env libero|robotwin|robodojo --task TASK ora.app.run, the backends' run cells (ora.orchestrator.backends.<backend>.run_cell), ora.app.run_services, ora.orchestrator.progress Binds the shipped single-gpu host for its own process, loads .env without overriding the shell, checks the Provider configuration offline, requires a clean checkout, reuses or (after confirmation) produces the RoboTwin seed manifest or RoboDojo card/task qualification with preflight's own validators, readies the perception services and binds a readiness report under 20 h old, composes a RunSpec with a fresh single-attempt cohort and opens ora interactive. Launch still needs --confirm-launch and a picker selection.
load_run_spec, resolve_run_spec, validate_run_plan ora.orchestrator.spec Source/asset-bound plan resolution and persisted plan validation.
resolve_tool_surface, PROFILE_CATALOG ora.agent.composition Registered tool definitions, schemas, roles, capabilities and effect contracts.
Default baseline catalog ora.agent.composition.baseline, ora.orchestrator.spec.defaults Select complete maintained compositions for fresh robot consumers.
run_episode ora.orchestrator.episode.coordinator Execute a resolved plan with policy/environment sessions; operator launches use the supervised CLI admission path.
ora-robot, ora.robot_client.Robot ora.robot_client, ora.agent.pi.robot_socket, ora.orchestrator.episode.script_actions Free play only (plan episode_mode: "play"): the agent's own scripts call the run's tools through the Supervisor. Standard library only; see free-play robot scripting.

spec.benchmark (ora spec robotwin|libero) composes one RoboTwin, LIBERO or LIBERO-Pro cell; backends.robodojo.spec (ora spec robodojo) composes a reviewed RoboDojo cell; backends.robocasa.spec and backends.robolab.spec (ora spec robocasa|robolab) compose one RoboCasa365 or RoboLab cell (backends). examples/official_suite demonstrates suite expansion. These select task/provider/resources and use the default resolver for policy composition.

Policy and tools

ora.agent.contracts defines policy-session contracts. The default agent core runs in TypeScript: ora-pi/ (on the Pi agent packages) owns the provider loop, request assembly, context management and agent-side evidence, and ora.agent.pi is its Python half, the policy session the Supervisor drives and the JSON-lines bridge that serves tools and observations. ora.agent.session_core is what that Python half builds on: the tool gateway, the static prefix and the observation and receipt projections. ora.agent.providers holds the Python OpenAI-compatible and Anthropic Messages adapters that preflight's provider probes use; ora-pi/src/provider/ reproduces both wire protocols byte for byte and sends every policy request. Credentials are environment inputs, not RunSpec values.

Tool runtime ownership is ora.agent.toolkit.host.runtime (the frame each episode builds, factory.build_tool_runtime), and each tool is the toolkit's (ora/agent/toolkit/tools/). A ToolSurface is the authority for advertised names and schemas; callers must not infer tools from module names. Observation, perception and geometry tools are read-only. Mutation tools submit proposals through the host mutation port and Supervisor.

observation.dump_state reads public current/historical state. robot.submit_action is the generic mutation boundary; selected surfaces use their declared motion/gripper/skill names without bypassing supervision. Argument refusals include their public constraints. Grasp/placement helpers may provide derived geometry, never privileged simulator labels.

ora.agent.context owns context projection and delivery. ora.agent.memory retains recoverable context artifact storage under its historical package name; it provides no task-file or cross-episode Memory service.

Free-play robot scripting

In a free-play run (plan episode_mode: "play", Pi core) the agent may script the robot from its own shell, the way a coding agent drives a device API. A benchmark run never opens this interface, and the model-visible bytes of every other run are unchanged.

Socket and environment. PiPlanner binds a unix socket (mode 0600) at <run>/native/robot.sock, or in a private 0700 directory under the temporary directory when that path is too long for a socket address, and announces it in native/robot-socket.json. The agent core's environment gains ORA_ROBOT_SOCKET, PATH led by <run>/native/robot-client/bin (only ora-robot) and PYTHONPATH=<run>/native/robot-client, a copy of ora.robot_client made when the socket opens; the core passes them to its shell tool. The core process itself never connects to the socket, so its Node --permission grants are unchanged. The client imports only the standard library and ora-robot runs python3 -S, so the agent's shell needs no ORA installation. Installed ORA also provides ora-robot as a console script.

Protocol ora.robot-socket.v1 (JSON lines; ora/robot_client/client.py). A request is {id, method, params, origin}, the answer {id, result} or {id, error: {code, message}} for a request the socket could not take.

Method Answer
tools.list The run's ToolSurface as delivered to the model: name, its provider wire_name (robot.submit_action is robot_submit_action), description, parameters (JSON Schema) and the declared effect (read_only, mutation, lifecycle). tools.call takes either spelling.
tools.call {name, arguments} The outcome: ok, call_id, effect, observation_step, the tool's result (runtime metadata removed), images (stored files, absolute paths) and a refusal's error. An executed world-changing call adds action, execution, receipt and the new observation.
observe The latest published observation: observation_step, observation_id, main_camera, per-camera images, proprioception, public_robot_facts, previous_execution, remaining_budget, runtime_notice, as the Supervisor's pointer carries them.
status turn_active, observation_step, queued, script call and script action counts, episode_mode, run_id.

ora-robot tools|call TOOL [--json '{...}'] [KEY=VALUE ...] [--save PATH]|observe [--save PATH] [--camera NAME]|status prints JSON; its exit status is 0 when the call ran, 1 when the tool failed or was refused and 2 when the socket is unreachable or the request malformed. Robot().call("observe", views=["agentview"]) is the Python equivalent.

One authority path. Connection threads answer tools.list, observe and status from snapshots the Supervisor's thread publishes, and queue every tools.call. Queued calls run on the Supervisor's thread while it waits on the core's act and is serving none of the core's requests (ScriptAwareRpcPeer); the core's own requests that arrive meanwhile wait until the script call is done. A call outside a policy turn, or still queued when the turn ends, is refused at once and untraced (no_active_turn, turn_ended); requests and refusals of every kind are logged in native/robot-socket.jsonl. A queued call takes the model's own path:

  • the agent trace records tool_call_proposed, tool_result and tool_image with the fields the core records for the model's calls plus payload.origin (kind: "script", the client, its command line, script and parent command, the peer pid); model_call_id and tool_call_id are the call's own script-call-NNNNNN;
  • a read-only call runs at once against the current observation;
  • a world-changing call is admitted first by the Supervisor (ScriptActionExecutor.admit: an active, non-terminal-lifecycle turn, the run neither ending nor interrupted, no environment boundary reached, no exhausted round budget, and the loop's own script_action_refusal()), else refused with script_action_refused and the reason; an environment boundary is reported only as turn_must_end. An admitted proposal is recorded as action_proposed and executed by the Supervisor inside the turn exactly like the policy's own proposal (provenance against the current observation, dispatch, receipt, decision and budget accounting, a fresh observation), recorded as environment_receipt and fresh_observation_published and in the Supervisor's events (action_submitted, motion_receipt and script_action). The script gets the receipt and the new observation;
  • lifecycle tools (finishing the episode) are the agent's own decision and refused to scripts (script_lifecycle_unavailable), as is any call after the agent's own action ended the turn.

Turns and decisions. A script's action is one robot decision of the current turn: the interaction goes policy_active → mutation_proposed → executing → fresh_observation_required → observation_ready → policy_active and the turn continues, so world changes stay one at a time and every one has its own observation step. The turn's model calls are counted once, when it ends. An environment boundary the action reached is settled by the loop after the turn. Once a script action ran in a turn, the model's own world-changing call in that turn is refused (world_changed_by_script): the core's turn is anchored to an observation the world has left, and one action per observation step keeps the trace valid. On a real cell (plan runtime rig_mode read or on, the play init's stop_scripts_on), once a script action's receipt carries failure_code guard_stop or operator_declined, the script's later world-changing calls in that turn are refused (script_stopped_by_operator, constraints.failure_code): a stop at the cell ends the script, not only its current motion (agent/pi/robot_socket.py). A core restart inside a turn in which a script acted is not resumed (the run ends as a fault), since the replayed shell command would act again.

Code mode (policy.code_mode)

A benchmark RunSpec with policy.code_mode (Pi core, not free play) makes code the way the model acts, on every backend (the plans it refuses are named below). It is RoboDojo's default since 2026-11-05 and off by default elsewhere: a RunSpec that names no policy.code_mode gets its baseline's code_mode, which robodojo_toolkit_v7 sets to {"library": "extended", "prompt": "v3", "source": true} (no forced preview; see policy selection), and "code_mode": null (or false) keeps tool calls. true is {"interface": "coding"}, the one interface ({"interface": "script"}, run_python and read_file, ran in none of 119 cohorts and was retired on 2026-11-01: a plan that names it, and a resolved contract without coding_tools, are refused, and its sealed runs keep their recorded definitions); limits may only tighten (ora/agent/code_mode/contract.py, contract ora.code-mode-script.v1). prompt names the generation of code mode's model-visible text: v2 (the default, recorded in the resolved contract) states the closed loop -- perceive, compute, act and check the receipt in one script, hand back only when perception is ambiguous, a call is refused or a check fails. v1, what every code-mode run sealed before v2 existed read (a resolved contract without prompt), was retired on 2026-10-31: {"prompt": "v1"} and such a contract are refused, and its sealed runs keep their recorded definitions. v3 rewrites the planner as a robot-programming environment for library: extended: a procedure (measure, compute every number in the script, act, read the typed result, re-measure against a stated tolerance), a short list of trigger lines that say when to reach for which function of the library (a capability the library gains later adds one line to that list), one worked script, and the frames card; its core and every layer after the planner are v2's. It is written for the extended library (it names robot.docs, typed results, allowance_left and ora_lib), so prompt: v3 with library: base is refused, naming both fields; a base contract that names no prompt is v2, whatever the default generation is. library selects what a script is given besides the tools: base (the default for now) is code mode as it was before the field, kept as the control, and extended the code-mode library; a resolved contract records library only when it is extended, so a contract without it, sealed or new, is base and composes, hashes and keeps its model-visible identity as before the field; any other value is refused. The plan's derived layer code_mode_v1 names the tools that became library functions (script_functions). A RunSpec sets it; ora run --env robodojo, ora spec robodojo and ora task runs on RoboDojo get the default, and there is no task-file field or ora run option to change it yet (edit the RunSpec's policy.code_mode).

What the model gets. The surface's lifecycle tools, check_task where the surface has it, report_issue, the artifact reader stay direct tools. The model's other tools are a coding agent's, named and shaped as Pi's defaults and confined to a persistent workspace /work (<run>/native/code-workspace): read(path, offset, limit), write(path, content), edit(path, edits[{oldText, newText}]) (they do not change the world) and bash(command, timeout) (coding.py). Every other advertised tool becomes a function of the robot library: a bash command's Python programs from robot import tools, handoff (robot.py). With library: base each function's description and argument schema are listed in the code tool's description. With extended the code tool's description lists one line per function instead -- the call with its arguments' nested shape (? marks an optional one, enums spelled out, [3] three numbers, [int; 2] two integers (pixels, which a validator refuses as floats), [x; 1-8] one to eight of x, to a depth and a character limit, with ... for what they leave out), the result's shape (what r["result"] holds, its arrays' items first) and the first sentence of its description, enough to write the common call without a lookup; a move_base that takes both forms is followed by the rule that joins them (docs.BASE_NOTE: all of x_m, y_m and yaw_deg, or any of forward_m, left_m and turn_deg, never a mix) -- then a library card generated by introspection: one line per public class of ora_lib (constructor, attributes, methods), per function (its signature, under the import that reaches it) and per public name of robot (target, handoff, explain, ToolRefused, a Result's fields, and query where it is served). robot.docs("<name>") is for what a line does not settle (after import robot): the call, the description and the arguments within 6,000 characters (the arguments cut in depth, then the description in sentences), then the name and size of each other part; robot.docs("<name>", "<part>") is one part whole (description, arguments, result, and explain for a tool that has stage templates), robot.docs("<name>", "all") the whole entry, robot.docs() the lines again, and help(tools.<name>) the same as robot.docs("<name>"). A name on the card is looked up the same way (robot.docs("target"), "Point", "Observation", "offset"): its signature and docstring, a class's members too. An unknown name is refused unknown_function, naming the names nearest to it. The index line, the entry and the card are generated (ora/agent/code_mode/docs.py), the first two from the same ToolSurface definition (a toolkit tool's description.json) and result schema: the entry keeps the description verbatim, every argument at every depth with its type, constraints and own description (units and frames as the schema states them), and the result's fields. What only some surfaces serve is told only there: a resolved extended contract records it as script_reads (contract.with_reads, decided in resolution from the surface): query where the tools run synchronously on the toolkit's data interface (RoboDojo's toolkit surfaces; a surface whose environment plans its moves serves none, and a call is refused as on the handlers), dry_run where moves are also planned on the policy side (toolkit v5). Elsewhere the description has no dry_run argument and no query lines, an entry no dry_run part, the card and an explanation name neither, and the planner composes without them; the runtime refusals stay. A lookup is the script RPC's read-only docs op, answered by the policy session (agent/pi/code_mode.py); it is no tool call, is not recorded as one and counts against no limit. compute is withheld: scripts compute in code. handoff(reason, **data) stops the script and hands control back with its reason first. A script's call to a tool scripts cannot make (check_task, the code tools themselves) is refused script_tool_unavailable, and a lifecycle tool's (finish_episode) script_lifecycle_unavailable as in free play; where the model has that tool the message says to call it directly, as its own tool call outside the script (agent/pi/code_mode.py). With extended the code tool's description states every per-command limit from the contract next to the actions and calls: the query allowance where queries or dry runs are served (32 queries and dry runs (180 s of them)), the programs' CPU time and memory (script_cpu_time_s, script_memory_mib), that /tmp is a fresh empty directory for every command (only /work keeps files), and which of the model's own tools a script cannot call (those of NOT_FROM_SCRIPTS and the lifecycle tools it has: check_task, finish_episode); a base description keeps its text (coding.LIMITS_WORDING). Also with extended, a script's call of a name that is no tool is refused unknown_tool with constraints.allowed the functions a script can call (the model's own tools and compute left out) and nearest, and for a name of ora_lib or robot the message gives its import (object_geometry is ora_lib's: from ora_lib import object_geometry), and a targets wrapper around a tool whose schema takes one arm's fields directly (RoboCasa365's, LIBERO's and RoboLab's move_pose, move_to, ...) is refused invalid_arguments, field targets, naming the form the tool takes (tools.move_pose(**target(p_world))), a dry run's too, where the schema alone said the mode fields were missing (code_mode/answers.py, refusal); with base such calls reach the tool as before. After the trusted terminal boundary the agent core refuses bash (a world mutation whatever its command does) with episode_terminal, as it refuses every world mutation in tool-call mode; code mode's message says no script or command runs any more, a read-only one included, and names the direct tools left, the advertised tools of DIRECT_TOOLS and the surface's lifecycle tools in the model's order (for example report_issue, check_task, finish_episode, artifact_read), which constraints.allowed lists too. That list holds the direct tools only: the workspace tools, which do not change the world, still answer as well. Tool-call mode's refusal keeps its message and empty constraints. The tool-call planner (policy-v5.md, or policy-v6.md) and core (evidence-action-loop-v8.md) are replaced by the code planner -- code-mode-coding-v2.md (or code-mode-workspace-v2.md), with prompt: v3 code-mode-coding-v3.md (or code-mode-workspace-v3.md) -- and the code core, code-policy-loop-v2.md (also with prompt: v3). With v3 the trigger lines of what only some surfaces serve are layers of their own after the planner (CODE_MODE_READ_LAYERS): code-mode-query-v1.md (robot.query) and code-mode-dry-run-v1.md, each where script_reads names it. They tell two questions apart: reach_check which of several poses the arm can hold, by inverse kinematics with no motion planned; dry_run whether the call in hand will run, by the plan the real call makes. The query layer also composes where no dry run is served, so it names none. The core leaves the round_static_facts message to round-static-facts-v1.md, which follows the core only where the context composition sends that message (native_slots_v4, the default bundles). On a surface whose moves run as joint trajectories (toolkit v5, toolkit.host.motion.joint_trajectory_surface), from v2, code-mode-trajectory-budget-v1.md follows the code planner whichever tool-call planner it replaced (each action at most what its description states; one shared allowance per script, up to 250 native actions per allowed action and never more than the episode has left; a move fitted to what is left and reported cut short, never stopped mid-path; one robot decision per script that spent any; recover_pose undoes one call of the script; grasp_execute runs whole). The layered robodojo_placement_toolkit_v2's bundle planner and core (prompt_bundles/toolkit_v3) and code-mode-toolkit-budget-v1.md, which restated their 20-per-primitive budget rules for code mode, were retired with that surface on 2026-11-01. From v2, the core evidence-action-loop-v9.md (bundle prompt_bundles/toolkit_v6, baseline robodojo_toolkit_v6) is replaced by its code form code-policy-loop-v3.md, with no round-static-facts layer after it (v9 leaves those to the context scheme's prompt), and robodojo_placement_toolkit_v5's prompt.md (turn protocol, numbers from compute, what the calls spend) is left out, since the code planner, the trajectory budget layer and the code core state each of its rules for a program (CODE_FORMS). Code mode refuses a plan that delivers tool-call text it has no code form of, instead of composing a prompt that states both loops: another evidence-action core, a prompt bundle's own planner or core, or another file-backed surface's prompt.md outside the manifest-only tool manual (orchestrator/spec/composition.py). An action's call returns receipt beside result (a synchronous toolkit tool's receipt is result.receipt) and no robot state, as the code tools' descriptions say.

The extended library. A contract whose library is extended also gives every command ora_lib (ora/agent/code_mode/ora_lib/, NumPy and SciPy only, bound read-only at /ora/lib/ora_lib; a bash command's programs import it) and a read-only copy of the current published observation at /ora/observation (library.py, index current.json, ora.code-mode-observation.v1). The copy holds each camera's depth (float32 metres along the optical axis), calibration and RGB (decoded to uint8), and the measured end-effector state. These are the artifacts geometry_query reads, resolved as the toolkit resolves them (the control pointer's identity against <run>/policy-observations/<id>/observation.json), and each file is copied only after it matches the manifest's hash and size. A camera that does not verify is listed under camera_errors, and when the observation is closed or missing, current.json says why. It also holds the mask of every segmented target recorded on that observation (the vision_ground and vision_segment calls of the model or of any script: the tools' own target records under <run>/openeta-tool-artifacts, each loaded as the tools load a target, against its manifest and hash; one that does not verify is listed under target_errors), which the next observation starts without. After each call of the script, before its answer returns, the copy follows the control pointer, so after an action the script reads the observation that action published. ora_lib provides:

  • Point(xyz, frame), Pixel(uv, camera), Pose(xyz, xyzw, frame) and Direction(v, frame), over the frames world, tcp:<arm> (the measured end-effector pose and its local axes), camera:<name> (OpenCV: right, down, forward) and pixel:<name>;
  • x.to(frame) converts with the current observation: into pixel:<name> it projects, out of it it lifts over the published depth;
  • combining values of different frames raises FrameError naming the conversion, and adding a bare list raises TypeError; NumPy reads a Point's or a Direction's numbers (np.asarray(p), np.round(d, 3)), which leaves the frame behind, and a ufunc over one (np.add(p, q)) raises;
  • current() (ora_lib.observation), the current observation: .camera(name), .pose(arm), .end_effectors, and .robot_facts, the public robot facts the observation message shows (each arm's gripper, mobile_base where there is one), on a surface that delivers them;
  • offset(value, dx, dy, dz, frame=...) (with frame="local", the pose's own axes), direction("left" | "right" | "up" | "down", view=camera, horizontal=False), pixels_to_world(camera, uv, window_px=3) (geometry_query's window median and pinhole lifting, for any number of pixels), and project(points, camera);
  • frames_card(), a text to print: the conventions, then for each camera where it is, how the world's axes show in its image (the image-right and image-up directions as world vectors, and in words where +X, +Y and +Z land) and whether it moves with the robot, then each arm's measured place and its local axes in world, all computed from the current observation with the frames layer's own arithmetic. A scene's calibration is per observation (docs/robots/frames-and-units.md) and not known when the prompt is composed, so the card is written in the sandbox from the observation, and the prompt: v3 planner has the model print it in its first script;
  • ora_lib.geometry, the toolkit lib's arithmetic on plain arrays (transform_points, transform_pose, mask_to_cloud, depth_inliers, principal_geometry, ...);
  • object_geometry(target) (ora_lib.vision), for a candidate that vision_ground or vision_segment returned on the current observation, its target_ref, or the observation's Target of it (current().target(target_ref)): the extent, principal axes, support height, height above support and mid height of the visible part of the object, in world, in metres. It measures the tool's own mask on the camera's published depth with the arithmetic of the tools' localization (vision.localize_mask; the fields keep its names: center_xyz_m, aabb_min_xyz_m, aabb_max_xyz_m, extent_xyz_m, principal_axes_world, principal_extents_m, largest_/middle_/smallest_extent_m with their ..._extent_axis_world, support_z_m, height_above_support_m, mid_height_z_m, support_point_count, the counts and fractions and a status of localized or insufficient_depth) and does it on every surface, whether or not that surface's tool result carries the extended fields; the overhead footprint fields are not computed. The result is a dict that also reads by attribute (g.support_z_m), with g.center, g.lower and g.upper as Points and g.axes, g.largest_axis, g.middle_axis and g.smallest_axis as Directions. It is the visible surface, not the object's whole shape, and the support height a single-view estimate from the depth just outside the mask. A target of another observation raises KeyError saying to segment again. robot.docs("object_geometry") (and help(object_geometry)) shows its documentation, from its signature and docstring, and the vision_ground and vision_segment entries carry an example of it (docs.EXAMPLES, naming the first camera that surface's schema names). Every example in an entry is written in the surface's own form: a dry-run example is the first of its tool's forms (under targets, one arm's fields, arms or strategy) that the surface's schema validates, and none where none does (docs.examples). ora_lib.vision.localize_mask(mask, depth, K, camera_to_world) and mask_summary(mask, depth) are the same measurements on plain arrays. The sandbox's interpreter has no OpenCV, so the lib's 8-connected components and elliptical dilation are written with SciPy (geometry.depth_inliers, geometry.dilate_disc) and held to OpenCV's, including which of two components of one size is the primary one. tests/ora/agent/code_mode/ora_lib holds object_geometry to the localization vision_ground returns for the same mask on the recorded RoboDojo frame: equal counts, status and strings, and floats within 1e-9 (the largest difference seen is 6e-17).

The lib's other perception and grasp fragments are not opened: grasp.candidates asks the grasp service, so it belongs to query; candidate_pose and controlled_pose convert that pool's poses and add nothing ora_lib.geometry does not do; compilation.compile_contact and clearance.estimate need the embodiment's compiler identity and jaw model, which the sandbox is not given.

Values are SI (metres, radians), and a name says when they are not (angle_deg). A contract without library, or with another value, has neither: its sandbox is unchanged.

ORA's code (source: true). With library: extended, policy.code_mode.source: true binds ORA's own files read-only under /ora/src, from the checkout the run executes, each at its repository path, so ora.a.b is /ora/src/ora/a/b.py (ora/agent/code_mode/library.py, source_files): every .py, .json and .md file of the toolkit's lib/ and tools/ (without check_task, finish_episode and report_issue) and of the motion planner (ora/environment/planners); the ora modules their Python imports, followed statically to the end (the toolkit's interface, ora/environment/controllers, ora/contracts); and each robot's public geometry (ora/policy/embodiments/*/manual-public-geometry-*.md and descriptor-public-geometry-*.json). A new file, robot or import is mounted with no list to update. What nothing mounted imports stays out: the evaluators, the simulator backends and the Supervisor (tests/ora/agent/code_mode/test_library.py refuses any of them, and credentials, by path and by content). It is for reading: it is not on PYTHONPATH, and a script still acts through robot. A resolved contract records source only when true, and which code a run read is the plan's commit.

Forced preview (retired). policy.code_mode.preview: true made a moving tool's dry_run how a move happened: the call returned a robot.Plan and .go() on it ran the path it planned. It was retired on 2026-11-05, when the code-mode comparison kept the dry run optional, and is refused, as is a resolved contract whose script_reads names preview (contract.RETIRED_PREVIEW_MESSAGE); a plan that names it composes only at its launch commit, and its sealed runs keep their recorded definitions. A dry run stays optional on every moving tool (dry_run=True, below).

Execution and evidence. A command runs in a fresh bubblewrap sandbox (sandbox.py, shell.py: no network, read-only system and interpreter, the workspace and a private /tmp writable; ORA_CODE_MODE_PYTHON, ORA_CODE_MODE_BWRAP; preflight checks code_mode_sandbox). With library: extended a workspace file cannot stand for a module anything imports: a command's Python runs with PYTHONSAFEPATH, /ora/lib first and, after site-packages, the script's directory (or the working directory) and /work (sitecustomize.py). So import numpy works beside a /work/inspect.py, python /work/inspect.py runs that file, and import inspect is the standard library's; the model's other modules import as before, with python -m, python -c and from a subdirectory. A base contract keeps Python's own path, the workspace first. It is one parent invocation of the Supervisor's ToolActionExecutor (orchestrator/episode/tool_execution.py; code_mode_execution.py binds it on every backend, counting one native action per action where the backend reports none; where the backend counts native actions but has no Supervisor-owned execution state to cap one action in the worker (RoboCasa365), one action may use what the episode has left and its measured spend is charged). A legacy action that did not start, or that the Supervisor refused, removes its proposal and reopens the observation it closed; any other failure of an action interrupts the parent invocation. A refused action stays in the parent's ledger with its reason and no spend; since it published nothing, the script's next action on the same observation carries the same action identity, which the ledger, the agent core and the trace verifier accept after a refusal only (evidence). A tool that commits a skill sequence (the closed-skill grasp_execute) runs its stage loop inside the script's parent invocation as one action where the backend's worker does not cap one action (RoboTwin): the script's call returns the staged receipt, the model's list of calls carries it in that call's entry, the post-close views tool-call mode shows with the next observation come back as that call's images, and the stage loop's time does not count against the script's wall time. Neither does any other action's time, so a long move does not spend the script's wall time. A committed sequence refused before it started also releases its skill ledger. A closed skill on a backend whose worker caps each action is refused at resolution (execution_state.per_action_capped, the predicate the coordinator binds that cap by), and RoboDojo runs code mode on its synchronous toolkit surface (robodojo_placement_toolkit_v5, baseline robodojo_toolkit_v6, the default; the layered robodojo_placement_toolkit_v2 with baseline robodojo_toolkit_v3 was retired on 2026-11-01), whose grasp_execute runs its stages inside the script's parent invocation. There the worker caps each action, and the script's parent lends each action it may run the most one action may use (joint_trajectory.native_action_cap): a joint trajectory's 250, since the surface's moves are joint trajectories. Each tool still asks for no more than its own budget, and a motion tool the script calls fits its plan to what the parent has left as well (ToolActionExecutor.nested_allowance, delivered in the tool context as script_native_actions_remaining; a tool-call context has none), so the parent's admission never stops a move mid-path; a move it cuts reports budget_limited.limited_by: script_native_actions_remaining. Each action names to the worker the script's own call of the tool (<call>#NNN and the tool's name) with the ordinal of the script's robot decision, so the worker keeps one recover_pose undo entry per arm-moving call of the script. Each of the script's calls is recorded under the reply's model call as <call>#NNN with payload.origin {kind: "code_mode", parent_tool_call_id, seq} (runs made before the rename say glue_code there and name the contract policy.glue_code; the trace verifier reads both); a legacy tool's submitted action is executed through the parent at once, a synchronous toolkit tool runs its primitives inside the same parent (a reentrant invocation). Every action is an action_proposed of the script's own call, and the parent's ledger is the call's ora.tool-execution.v1 evidence: the agent core ends the turn when it spent anything, and the call counts as one robot decision. Per script at most 12 actions (and half the decisions left), 24 other calls, 300 s (not counting a committed skill's stage loop), 2 GiB; the result carries the script's value or output, error, calls (each call, tool and ok, which says the call was answered, not that its action succeeded; a failed action's entry adds its summary line, a planner refusal's own words included, so the model reads why it failed even when the script prints only a code), actions_executed, handed_back, the workspace snapshot (each file's sha256, the bytes kept under <run>/native/code-workspace-objects) and the images its calls returned. A program that ends while the host is answering one of its calls (its own timeout, a signal, a resource limit) leaves the answer nowhere to go; the call ran and is recorded, and the command ends failed with the command's exit_code and error_detail {type: ProgramEnded, code: ended_during_call, calls, message}, plus signal and limit where the exit status shows one (SIGXCPU: the CPU time limit; SIGXFSZ: the file size limit), and the run goes on (shell.py; before 2026-11-03 this ended the run tool_execution_interrupted). The trace's privileged-field audit skips what the script itself returned, printed or handed back, and the arguments it sent with its calls, since its calls' results are audited on their own (evidence); the seal takes the workspace's files under whatever names the model gave them, credential-like ones included. Replay programs group a script's steps under its source, a skill sequence's stage steps (<action_id>:NN-<stage>) too.

Host prerequisites. The sandbox needs bubblewrap (bwrap on PATH, at ~/.local/bin/bwrap, or named by ORA_CODE_MODE_BWRAP) and unprivileged user namespaces, which ORA does not install. code_mode_sandbox checks both before the interpreter and refuses a plan with what to install or set: bubblewrap (apt-get install bubblewrap, or the package unpacked without sudo), and for namespaces user.max_user_namespaces above 0, kernel.unprivileged_userns_clone=1 on Debian and Ubuntu, and on Ubuntu 23.10 and later kernel.apparmor_restrict_unprivileged_userns=0 or an AppArmor profile for bwrap. ora doctor --env robodojo (an environment whose default runs code mode) reports code_mode_bwrap, code_mode_user_namespaces and code_mode_interpreter.

The interpreter. ora setup --env robodojo builds it (component code-mode) at envs/code-mode/bin/python under its prefix (ORA_GPU_PREFIX, else ~/.local/share/ora/gpu) and writes ORA_CODE_MODE_PYTHON to .env. The sandbox uses ORA_CODE_MODE_PYTHON when it is set (an explicit value wins and must be executable), else that path, so a launch that does not read .env still finds an interpreter setup built under the default or exported prefix. ORA_CODE_MODE_PYTHON is a Python 3.11 built from the lock ora/agent/code_mode/sandbox-requirements.txt: NumPy 1.26.4 and SciPy 1.13.1, Pillow, scikit-image and Shapely, and their dependencies, each at an exact version with its hashes (uv venv --python 3.11 DIR && uv pip install --python DIR/bin/python --require-hashes --no-deps --only-binary :all: --compile-bytecode -r ora/agent/code_mode/sandbox-requirements.txt; the lock's header says how it is regenerated from sandbox-requirements.in). Without one, the refusal names ORA_CODE_MODE_PYTHON, the path it looked at, ora setup --env robodojo and that build. The code_mode_sandbox preflight check imports every locked package inside the sandbox and refuses an interpreter where one is missing, at another version or does not import, naming the lock, the package, both versions and that command; its detail records the interpreter it checked (interpreter: executable, Python version, the locked packages' versions and the lock's sha256) in the run's preflight.json. Nothing of it reaches the model.

Typed results, filled parameters and the script allowance (library: extended). With policy.code_mode.library: extended every tools.<name>(...) call in a bash command's program returns a Result (robot.py, with ORA_CODE_MODE_LIBRARY=extended). A Result is the answer as before, a dict (r["result"], r["receipt"] and json.dumps(r) unchanged, the whole answer also as r.raw), with its outcome read into fields: ok, status, failure_code, failure_stage, summary (the action's summary line, or the refusal's message: why the call was refused and what near it would work), pose_after (world [x, y, z, qx, qy, qz, qw]), target_error_m, target_error_deg, cut_short (True for a move its budget stopped on its path, whose target_error_m is then the distance left to the target and target_error_deg None), contact, and the public gripper signals measured_aperture_mm, measured_opening and commanded_opening (0 closed to 1 open) and gripper_command (open or close); r.arms holds each arm's pose, errors and gripper signals, and a field of the result is its one targeted arm's (the larger error when two arms were targeted); r.reused is True for a kept answer (below). r.ok is true when the action's status is reached, executed or completed with no failure_code (a read-only call: no error, no success: false, no status: failed); r["ok"] stays the answer's own flag, true for every call not refused. A refused call still raises ToolRefused, whose result is its Result (status refused, failure_code the error's code). An answer that is not ok and carries no error, but whose items failed with codes of their own (mark_point's marks, vision_segment's queries), gets one from the policy session: the most frequent item code and a message that counts every code with the first message given for it (8 of 8 marks failed: inconsistent_mark x6 (independent RGB-D measurements disagree by 0.19 m, ...), depth_discontinuity x2 (...)), so ToolRefused says why (it said mark_point: refused), and the call's entry in the result's calls carries the code and that message as summary (code_mode/answers.py, item_errors; the call's record and its explanation keep the tool's own answer). A field the backend's answer does not carry is None; every field is read from what the script already receives (the result's causal projection and the receipt's public motion effect), so nothing is added to what a script may see. Where they are read, per tool:

tool (backends) outcome target_error_* gripper signals contact
move_pose, move_to, rotate_wrist, rotate_pitch, recover_pose, return_home, wait_ticks, move_base on LIBERO, RoboTwin, RoboCasa365, RoboLab (the script's parent executes the action) receipt.status, receipt.failure_code, receipt.failure_stage receipt.detail.arms.<arm>.pose_error (translation_m; orientation_rad, or orientation_deg converted) RoboTwin: receipt.detail.arms.<arm>.command_preservation.gripper_command_target_after receipt.physical_cause (blocked_by_contact, pushed_by_contact), LIBERO receipt.detail.contact_motion.contact_estimated, force_threshold_exceeded; RoboCasa365 and RoboLab receipt.detail.endpoint.stop_reason contact_detected (the gripper contact stop), RoboCasa365 receipt.detail.base.stop_reason base_contact
the same on RoboDojo (synchronous toolkit tools) result.receipt.status, failure_code, failure_stage result.receipt.detail.arms.<arm>.pose_error result.receipt.detail.arms.<arm>.gripper_outcome, detail.gripper_targets_effective.<arm> as above, under result.receipt
set_gripper as its backend's motion tools none LIBERO receipt.detail.gripper_outcome (its one gripper_targets_effective arm); RoboCasa365, RoboLab, RoboDojo detail.arms.<arm>.gripper_outcome (measured_aperture_mm, measured_opening_normalized, commanded_opening_normalized; RoboDojo reports no calibrated aperture in mm); RoboTwin only the command target as above
grasp_execute, RoboTwin (a committed skill sequence) receipt.status (completed, stopped), receipt.failure_stage (a stage) and failure_code none receipt.detail.verification.gripper_opening_m, in mm none
grasp_execute, RoboDojo (multi-stage synchronous) result.status (executed, stopped); the first of result.stages whose status is not executed, skipped, not_requested or terminated gives failure_stage (its stage) and failure_code (its reason) the latest stage receipt's pose_error the latest stage receipt's gripper_outcome; result.verification.gripper_opening_m any stage receipt's estimate
observe result.status if any none result.public_robot_facts.end_effectors.<arm>.gripper (measured_aperture_mm, measured_opening_normalized, commanded_opening_normalized, command_target) none
perception and measurement tools (vision_ground, vision_segment, geometry_query, mark_point, grasp_plan, align_plan) result.status if any (mark_point: solved, partial, failed), result.error.code none none none

pose_after is observe's result.public_robot_facts.end_effectors.<arm>.pose_xyz_xyzw, or an unprojected receipt's after.<arm>.pose_xyz_xyzw. None of the five backends' projected action effects carries the pose after an action: each states it in the next observation's public robot facts. So after an action (an answer with action, the number the host gives the script's world-changing call) pose_after is each arm's measured pose in the observation that action published, read in the sandbox from the mounted observation (/ora/observation/current.json, which the host brought up to date before the answer returned), the same measurement observe reports: Result.arms[arm].pose_after for every arm measured, and the result's own pose_after for the arm the receipt names or the only arm measured (None for two arms and no name). It is None where no observation is mounted or the current one is closed, and a receipt's own after pose wins. Likewise whether a grasp holds is not a field: the script judges it from the gripper signals, the views and a re-measurement. move_pose and move_to take typed values in place of their mode parameters, filled in before the call is sent (target(...) builds one arm's move_pose target): a value is an object with frame and xyz (a point), xyz and xyzw (a pose) or v (a direction), such as ora_lib's Point, Pose and Direction, its to_json(), or the dict {"frame": ..., "xyz": ...}. In move_pose's targets.<arm>, a point in tcp:<arm> becomes position_mode: delta, position_frame: end_effector and translation_m; a point in world becomes position_mode: absolute and position_m; a world pose also orientation_mode: absolute_quaternion; {"position": ..., "approach": d1, "jaw_line": d2} with two world directions becomes orientation_mode: world_axes with approach_world and jaw_line_world; otherwise the orientation is held. move_to's targets.<arm> takes a world point, and so does a single-arm surface's move_to(position_m=...). A value in another frame (camera:<name>, pixel:<name>, the other arm's tcp), a batch of points, a frame-less list, or library keys mixed with the tool's own is refused in the script with the conversion to make; a target already in the tool's form, and every other tool's arguments, pass unchanged. target(..., interaction=...) writes the label move_pose reads, and interaction on a typed target passes through; a surface whose move_pose takes it in each arm's target uses targets={arm: target(...)}, a single-arm surface (LIBERO, RoboCasa365, RoboLab: no targets) move_pose(**target(...)); target's documentation, the v3 planner's trigger line and its worked script (<move>, filled in the surface's form) state both and write neither literally. Where the schema takes interaction, the code tool's description says after move_pose's line to label every move, when each value applies, and shows the call in that surface's spelling (docs.interaction_note); where it does not (native_atomic_causal_v1, local_atomic_cpu_v1), neither that line, the card nor robot.docs("target") names it. No surface's move_to takes one. Every bash result of an extended contract also states what is left of the script's allowance, allowance_left: {"actions": n, "calls": m, "queries": {"count": q, "seconds": t}} (its action limit, at most max_actions_per_script and half the robot decisions left, less the world-changing calls it made; max_calls_per_script less its other calls; and the query allowance below), which the script tool's result schema declares (runtime.extra_result_schemas). Without library, or with library: base, a call returns exactly the answer it returns today, its arguments are sent as given, the sandbox binds no robot.py beside the runner and the result has no allowance_left.

Reused perception results (library: extended). The policy session keeps the answers of a script's vision_ground, vision_segment and geometry_query calls (the toolkit's reads of the published observation, under a legacy surface's dotted names too; ora/agent/code_mode/reuse.py) for the current observation, where the surface classes the call read-only and the call succeeded. The same call with the same arguments, as the tool receives them, on the same observation, in that script or a later one of the same turn, returns the kept answer with reused: true (Result.reused; its entry in the result's calls has reused: true too). No tool runs: the call is not recorded as a nested call (as a docs lookup is not), counts against neither max_calls_per_script nor allowance_left (a kept answer is still given when the limit is reached), and carries no images again. A new observation, whether an action or the model's own call published it, starts afresh. A refused or failed call, a world-changing call and the read-only tools that persist a mark (mark_point), ask the grasp service or the planner (grasp_plan, align_plan) or return the images (observe) are never kept. Tool-call mode is unchanged, as is a contract without library: extended.

Understanding a call (explain, library: extended). robot.explain(r) returns what one call did in causal order, as a deterministic rendering, not a model call, so it is the same on every replay: a header (vision_ground(head, "red cup") 2 candidates), numbered stages, each with what it did, the criterion, the measured value and -> verdict, then conclusion: and, for a failed call, next: with what can be done. It reads the tool's result as the script reads it, the refusal and who gave it (tool or supervisor: code mode's limits, the executor), the environment receipt where an action ran and the stage events the tool recorded with stage(name, **fields) for the decisions its result does not carry (a mask or candidate a cap cut, the depth window it resolved, whether a grounding was reused). stage (agent/toolkit/interface/stages.py) is a no-op unless a caller collects: tool-call mode never does, so no tool's result, ledger or journal changes, and code mode collects around each script call and keeps the events out of every result. Each tool's stage template, tools/<name>/explain.json (ora.toolkit-explain.v1, beside description.json), lists its stages, the result fields and events each reads and one line per stage; the renderer (agent/toolkit/explain.py) fills it in, and the tests hold every field it reads to the tool's schemas, to the events the tool's source records and to the answers recorded on sealed runs. The templates cover vision_ground, vision_segment, geometry_query and grasp_plan, and the arm-moving tools move_pose, move_to, rotate_wrist, rotate_pitch, recover_pose and return_home (stages: what compiling found per arm -- the translation and turn from the measured pose, the read-only IK of the target and, when it does not solve, how far along the straight line it is reachable and the smallest turn that makes it solvable, the observed depth clearance --, the route and plan, the screening against the arm itself, the table top and the other arm, the native-action budget, the predicted end pose of a dry run, and what the executed trajectory did, from the receipt; move_pose records the compiling findings as the stage event compiled, which move_to and the rotations share); a move the receipt reports not reached is a failed call and carries its explanation like a refused one, and explain of any other tool is refused no_explanation, naming the tools that have one. r is a Result, the ToolRefused of a refused call or a call id: every extended call's answer carries its call_id (<call>#NNN, the id its record has), and explain answers for any call of the run, in a later script and after a restart of the session too (the session keeps the latest 256 calls in memory and renders older ones from the inputs their records hold, below); an id the run never gave a call is unknown_call. A failed call (refused, or one its template calls failed: no candidate, a partial segmentation, no pixel with valid depth, no reachable grasp) carries its explanation without being asked: r.explain, and explain in its entry of the script result's calls (declared in runtime.extra_result_schemas; each cut at 1,800 characters, and the calls of one script result carry at most 6,000 characters of them: ATTACHED_CHARS and SCRIPT_CHARS; robot.explain(r) returns the text whole). A request is the script RPC's read-only explain op (sandbox.READ_OPS), answered by the policy session (agent/pi/code_mode.py): not a tool call and against no limit, but on the record as a nested robot.explain call of the script (below). robot.docs(name, "explain") lists a tool's stages and events. Without library, or with library: base, a call's answer has no call_id or explain, no stage event is collected and the sandbox serves no such op.

Before an action (dry_run). Every action that moves the robot takes dry_run, on every backend, in tool-call mode ("dry_run": true on the tool, declared by the surface capability action_dry_run_v1, read-only by the Supervisor) and in code mode (tools.move_pose(..., dry_run=True), library: extended), with one result, interface/dry_run.RESULT_SCHEMA: move_pose, move_to, rotate_wrist, rotate_pitch, recover_pose, return_home, set_gripper, grasp_execute and move_base. Reads have none, and neither does wait_ticks: nothing moves. It takes the arguments of the real call and returns what the call would do without doing it: the route, the screening where one ran, the native actions against the budget, each arm's predicted end pose, and the preview of lib/action_preview.py: per arm the native actions up to the first contact, how far the hand travels (hand_travel_m), all its turning (hand_turn_deg), how far the path's highest point is above the higher of its two ends and where (rise_above_ends_m, 0 where an end is highest, and rise_at_fraction; the jaw contact centre's height, or the controlled point's where the hand publishes no jaw geometry; the summary says "rises 19 mm above its higher end at 52% of the path"), what the jaws hold (held_object, from the measured state whatever closed them: the last command was close and the jaws stopped apart; target_ref, the target named when they closed or null, extent localized for that target's localized box, between_jaws for only the box between the jaws at their measured opening, or unknown, box_size_m and jaw_gap_m; that box is swept in clearance and drawn where the hand is and where it ends, and the summary line opens with it), the least clearance between the jaws and what the depth images show, on the scene as the images show it and not on the planner's world, leaving out the last 5 cm at each end of the path, where a planner clears the hand's surroundings and the object being approached is removed on purpose (clearance: measured with clearance_m, at_fraction, position_m, part and camera, and where a finger box or a held object's box holds a seen point clearance_m 0 with inside_m, how far the deepest such point lies inside it, which at_fraction and position_m then name and the summary states as "the jaws reach 12 mm into what the depth shows at 30% of the path"; a plan that does so stays feasible, as the real call runs it; beyond past 10 cm; ends_only for a path no longer than its ends; unknown with its reason; enters_cleared_space with at_fraction, position_m and part where the jaws enter that space), segments in the order they would run, one line per arm (summary), and one picture (image, images_base64). The picture is the one renderer _preview_render: the planned path over time, the published calibration and the latest image of the cameras that see most of it, at most two, taken from the observation manifest and never by name, with start, end, time marks, the point of least clearance and where the jaws enter what a planner cleared. A dashed line is commanded, not planned: a servo's line, which only its run times, or what follows contact. set_gripper shows the jaw width and finger positions it would command; grasp_execute shows every planned segment up to contact and marks what follows the close not_predicted. Everything here is planner output, forward kinematics, public calibration and public depth: no physics is rolled out, so a preview means the same on a real robot (claim_boundary says what it does not cover: no contact, no payload, no response of the world, nothing after the first contact, and what clearance covers). Clearance leaves out the points near each hand and along the moving arm's measured chain of joints (contracts/action_plan.body_points: forward kinematics alone), so what stands right beside them is not seen. A run whose latency profile turns preview_images off keeps every number and draws no picture (image says so; latency profile).

How a dry run is answered. Where the policy side plans (RoboDojo) the tool runs lib.motion_plan's move.plan or recovery.plan over the read-only kinematics query and stops before it executes. Where the environment plans, the tool compiles and validates the action as for a real call and stops at the point it would hand it over (dry_run.Proposed, raised by _persist_action and NoActions.submit_action); agent/toolkit/host/action_preview.py asks the same planner the same question over the read-only align_plan bridge (ora.action-plan-request.v1, answered ora.action-plan.v1 by a session's plan_action), which never steps the world. A backend that cannot answer without stepping it says so and the call is refused dry_run_unavailable with constraints.reason: a RoboTwin recovery after a blocked move retreats first and plans from where that stops. A closed-loop servo has no path until it runs: a local move and move_base are answered with the line they are commanded along, planned: false, and no native actions; RoboCasa's move_base answer carries the check its real call makes (the footprint and the arm it carries along the servo's path), and is refused (base_path_in_collision, with robot_part) where that check refuses. The flag reaches the tool out of band (interface/dry_run.dry, a context variable): the runtime strips the argument (ToolRuntime.invoke, toolkit invoke_parent), and nothing in a dry run can act: the data interface a toolkit tool gets has no action capability, no action file is written and the observation stays open, so it produces no action_proposed, no environment receipt, no ledger entry and spends no native action or robot decision. In a script it is a read-only nested call (origin.dry_run: true, effect read_only, its record in calls with dry_run: true, and summary, and its picture among the script's frames, whether the script prints them or not); it counts against the script's query allowance (max_queries_per_script, query_time_s: _code_mode_charge_query, script_query_limit past it) and against neither max_calls_per_script nor max_actions_per_script. The answer is the record in degrees, through the causal filter, with explain attached where the tool has one, and a Plan (a Result) reads it: dry_run, feasible, summary, predicted_pose and end_joints_deg (the one arm it moves; predicted_poses every arm's), route, screening, failure_code and failure_stage; a run's fields (ok, status, pose_after, the receipt's) raise PlanNotRun, since nothing has run (if r.ok read a plan as a run and pushed with open jaws), and robot.docs("<tool>", "dry_run") says so (it said .feasible (also .ok) until 2026-11-06). In tool-call mode and in code mode, whatever the library, each arm's record also carries predicted_approach_world and predicted_jaw_line_world after predicted_pose (user decision 2026-11-06, on every backend): the predicted pose's rotation times the controlled point's local approach and closing axes of the surface's view_config.controlled_frame_convention (the axes the published end-effector facts give the measured pose), unit vectors rounded to 5 decimals as move_pose's world_axes takes them, none where the surface publishes no convention, as on the YAM station (code_mode/answers.py, predicted_axes, which code mode's answer and tool-call mode's projection, session_core/domain.py, both apply; RESULT_SCHEMA declares both). The sealed record keeps the planner's own fields: the axes are added where the model reads the record. A plan the real call would refuse before it moved is the answer (feasible: false, the real call's code, the refusal under refusal, a summary line with the code and the refusal's own words, which for an environment's answer without a message are the planner's first sentence and the refusal detail's as a receipt's summary says them, and a picture of what was asked), not an error; a malformed argument, or a kinematics service that cannot answer (planner_failed), is a refusal of the call, as it is for the real one.

Running what was previewed. The same request on the same observation runs the trajectory the preview showed, with no new argument, and any change of observation, state, budget or request plans as ever. On the policy side the plan is kept in the tool state (tool.kept_plans, lib/motion_plan/kept.py), keyed by the observation's identity and every input of the plan; where the environment plans it is kept where it is made (controllers/kept_plans.KeptPlans, keyed by the planner request, world hash and start joints included, or, on the YAM station, by the action and the measured joints). A receipt says so: ran_previewed_plan: true. A compound action runs its own stages, so only a move that starts on the previewed observation can reuse its plan: a grasp_execute that opens its jaws first plans its path again. ora replay RUN --incident N --preview --report OUT asks a RoboDojo action's dry run at the state it ran from and writes OUT/preview.png. robot.docs("<tool>", "dry_run") describes the record, and the tool's arguments part and one example show the argument; on a surface whose script_reads does not name dry_run none of that is shown (above). Predicted against executed end poses on recorded runs: see tests/ora/agent/toolkit/tools/move_pose/test_dry_run.py and tests/data/code_mode/motion-predictions.json.

Reading the robot model before a move (robot.query, library: extended). robot.query(name, **arguments) returns a lower-level read of the environment's robot model or of the measured state, for the numbers a script wants before it acts: ik (one arm's joint solutions for a sequence of world poses, each seeded from the previous: motion_plan.kinematics.ik_chain), fk (the controlled frame's world pose at joint vectors), screen_path (joint polylines against the arm's own links, the table top and the other arm), reach_check (up to 16 poses, lib.motion.reach_check), probe_motion (up to 12 poses planned without executing, with the verdict and refusal code of a fast free-space move_pose where the motion tools plan their moves: it takes seconds and is stale after any action), align_plan (up to 12 poses ranked by IK, lib.motion.align_plan) and robot_state (lib.observation.robot_state of the published proprioception). Poses are [x, y, z, qx, qy, qz, qw] in world (metres, xyzw; an ora_lib Pose in world is accepted, one in another frame is refused with the conversion to make) and every angle is in degrees, as every angle a policy sees: the arguments are seed_joints_deg, joints_deg, knots_deg and max_joint_step_deg, and an answer's ..._rad fields are their ..._deg (the table of composition/surface/units.py, to 1e-6 degrees); everything else of the lib's answer is passed on. robot.docs("query_<name>") has each query's arguments, result and an example, and the code tool's description lists one line per query after the functions, where the contract's script_reads names query. A query is the script RPC's read-only query op (sandbox.READ_OPS), answered by the policy session over the tools' own data interface (code_mode/query.py; toolkit/host/query.py binds it to the current observation and records nothing: no I/O journal event, no gap file): it is not a tool call, but is on the record as a nested robot.query call of the script (below), and counts against neither max_calls_per_script nor max_actions_per_script. It moves nothing and reads only what a robot instance could read through the data interface. Where the environment cannot answer it says query_unavailable and why, and nothing is faked: a surface that runs no toolkit tools (the legacy LIBERO and RoboTwin surfaces), no read-only IK bridge, a backend that serves no kinematics query, or no motion-probe bridge. The environment's own refusal of an argument (an arm it does not have) keeps its code, field and allowed values.

A script's queries, and the dry runs that share the allowance, spend a per-script query allowance: max_queries_per_script (32) queries and query_time_s (180) seconds, contract limits of library: extended that may only tighten, recorded with it (a base contract names neither, and refuses them), and stated, from the contract, in the code tool's description. ToolError script_query_limit, with constraints (max_queries, query_time_s, queries, query_s), refuses a query once either is spent; the last admitted query may overrun the seconds, since its cost is known only when it ends. A query refused for its arguments, or for no interface to bind, is not counted. The defaults come from what a query costs on RoboDojo's worker in recent runs: an fk takes 0.03 s, a screen_path 0.04 s and an ik_chain 0.2 s at the median (20 poses), 0.8 s at the 90th percentile and 3.6 s at worst (90 poses); 60 s is a fifth of the script's wall time (300 s). Without library: extended, robot.query is not in a script's robot and raises in a command (it needs the extended library), the host refuses the op (op_unavailable) and the result has no allowance_left.

What a script asked of the library, on the record (library: extended). Each robot.query and robot.explain request, answered or refused, is recorded as a nested call of the script, as its tool calls are (agent/pi/code_mode.py, _code_mode_record_op; ora/agent/code_mode/record.py): a tool_call_proposed/tool_result pair under the reply's model call, named robot.query or robot.explain (robot.inspect in a run sealed before that read was retired on 2026-11-01), effect read_only, origin {kind: code_mode, parent_tool_call_id, seq, op}, its arguments what was asked ({"name": <the query, or None for explain>, "arguments": <the rest: the query's arguments, or {"call_id": ...}>}) and its result artifact what was returned. It takes the next seq of the script's calls, so the calls after it number past it (their call_id and their call in the result's calls); it is listed in no calls entry and counts against no call limit. A docs lookup, which returns only static text, and a reused perception answer, whose call was recorded when it ran, are not recorded. The tool_result of every call an extended script makes, a dry run included, also records the inputs its explanation renders from (payload.explain_inputs, an artifact ora.code-mode-explain-inputs.v1): the tool and its stage template's identity, the arguments as the script gave them, what the script read of the call (result, a refused call's error, a legacy action's receipt) and the stage events its tool recorded. Where a call submits an action the Supervisor executes after the tool returns (LIBERO's and RoboTwin's surfaces), its result is recorded once that action ran, after the action's own events, so the inputs hold what the script read of it. The evaluation of a run with the extended library renders again, from those records alone, every explanation a script read -- each robot.explain answer and each explain in a script result's calls -- and invalidates a run whose text they do not reproduce (agent_trace:code_mode_explain_not_reproduced:<record>, or code_mode_explain_without_inputs for an explained call that has none); an explanation rendered from another template than the evaluating code has is not held to it. A request's pair is no tool call for any reader of the trace (evidence.agent_events.library_op): the trace verifier counts no mutation for it, and the run report's tool counts, ora toolkit replay's list and ordinals (and the live index that numbers the calls it records), the Viewer's process timeline, the terminal transcript and status line, the world view and the Inspect export leave it out. The model reads the script's result only, as before. Without library: extended no request is served and a call's records are those it wrote before: the same events, fields and order.

Environment boundary

ora.environment defines transport-neutral sessions, descriptors, registry and Synthetic. The local_rpc worker uses the selected simulator's explicit interpreter. Backend implementation lives in ora.environment.backends.robotwin, libero_pro, robodojo, robocasa or robolab and is loaded in the isolated worker. motion_action_v3 also carries move_base (a world-frame base target), admitted only where the environment declares a mobile base (RoboCasa365). A motion_action_v3 move_pose may carry speed, the end-effector speed the move asks for (ora.contracts.motion_speed); the pose tools send it only on a surface that declares end_effector_speed_v1 (LIBERO, RoboTwin, RoboCasa365, RoboLab), and ora.environment.controllers.motion_pace paces any planner's route under it and checks the wrist, or caps a servo's step per tick where no joint path is planned (RoboLab) (motion speed and wrist checks).

ora.environment.benchmarks holds host-safe task identities, source versions and suite expansion. ora.environment.controllers holds shared controller/safety contracts and source-bound profiles. Simulator modules do not belong in host-safe planning or action-contract imports.

Only the environment's official boundary supplies the boolean task verdict. Synthetic has no such boolean. A model's finish_episode or natural-language claim cannot override official evidence.

RoboTwin's read-only IK

The internal reach check (compiled_pose.targets.<arm>.reach_along_request, the grasp_plan IK selection) and align_plan answer on RoboTwin with the shared planner's IK (backends/robotwin/shared_motion.py): one solve per query, seeded from the measured joints or a chained query's solution, in the public-depth world a plan to that pose would see, with the other arm's spheres at its measured joints. An ik_failed row means no solution held the public TCP within the arrival bound; start_unreachable means the query it was chained onto failed. The model is robotwin_reach_ik_depth_world_v1 (contracts/robotwin_reach.py). A session with no bound planner refuses both: a direct session or a qualification has no public answer to give.

matches_move_pose_admission is false, as on LIBERO and on RoboDojo with a planner bound: the check is the solver a global route plans through, but admission also plans a trajectory and validates it. Only free_space always sends the exact pose to this solver (controllers/motion_transaction.select_motion_strategy); a small precision turn and a short contact_approach run locally, and a longer contact_approach solves a pre-contact pose. Measured on 2026-11-01: one query took 0.8-1.2 s in a run, its world included, a 32-query request on a recorded snapshot 2.7 s, and each new physical state adds one 1.2 MB snapshot of the depth world. Offline on 200 recorded free moves, each in its own observation's world, the planner planned 178: 151 of the 158 that reached, 24 of the 39 that did not.

On RoboDojo the check is the shared planner's IK in the world a plan to the pose would see (backends/robodojo/reach_check.py, ik_model robodojo_reach_ik_depth_world_v1), so interaction changes no answer and route is null. It plans no path: matches_move_pose_admission is false, and robot.query("probe_motion") and a dry run give the move's verdict. With no answer every row is unreachable with its reason: stale_observation (ask again after the next observation), no_planner or planner_error. Each call records its time in native/motion-planner/ik.jsonl. Sealed runs keep the SDK check's answers and their reasons.

RoboDojo's align_plan and probe_motion answer from the same IK, one solve per pose from the measured joints (backends/robodojo/reachability.py, solve_batch), so their rows carry the reasons above. probe_motion plans nothing. It is grasp_execute's precommit gate, so passing that gate means the IK holds the pregrasp and contact poses in the world a plan to them would see: a goal with a fingertip below the support is refused, and a blocked or winding path is not, which leaves that refusal to the stage, after the gripper has opened. Its variants carry plan_ref: null and the reason as failure.code, and it writes nothing under native/motion-probes/. motion_probe_ik_candidate_feedback_v1 still selects the v2 request, which gets this same record: one IK solve has no per-seed counts, so constraint_rejection_counts, planning_diagnostics and ik_validation_artifact are gone here. A session whose runtime names no planner answers no pose in either, with reason no_planner as reach_check does; play scenes bind the planner as the benchmark does. Sealed runs keep the SDK answers they recorded.

measured_disagreement left the reach result: it existed for the damped-least-squares check this replaced, and no backend has a measured value now. A sealed run keeps the definitions and answers it recorded.

Evidence and viewer

ora.agent.evidence owns canonical request/response, tool, action, state and artifact records. ora.orchestrator.evaluation.evaluate validates and seals a run; revalidation writes independent later reports. Exported SFT conversations are derived training projections, not the canonical trace.

The viewer reads indexed runs, trajectories and media. Original captured images/video and reconstructed replay are distinct evidence types. Rendering or cache reconstruction never changes the recorded verdict or seal. Viewer documentation describes the local read-only interface.

Schema identifiers use ora.*. The distribution is ora-agent; Python imports and commands use ora. Older evidence namespaces are not silently aliased by this release.

Structured tool errors and repeated identical requests

Public refusals identify the failed stage and stable code, expose the allowed public constraint and describe recovery supported by the interface. Private paths, object state and exception stacks remain outside policy feedback. Retrying an identical invalid request does not make it admissible; the Native loop records tool results and recovery evidence without pretending a refused proposal executed.

Tool description consistency

Canonical tool help, closed input schemas, public result schemas and actual handlers must agree. Help states when to select the tool, effects, immediate/deferred evidence, limits, non-guarantees and recovery. Both provider projections derive from those same definitions. compute performs admitted pure geometry/calculation; policy-visible numeric conversion must not rely on undocumented mental arithmetic. See the ToolSurface guide and description consistency tests.

Published limits and stated refusals

Every numeric constraint in help/refusals has a source owner and actual consumer. Publish the same units, frame, inequalities and applicable conditions that the admission check enforces. Derived values must be computed by the responsible helper. A missing or uncalibrated quantity remains unknown; do not present nominal geometry as a measured fact or weaken an execution gate to match prose.

Source: docs/reference/public-interfaces.md