Run ordered action batches

Validate and run one ordered model action array without automatic replay.

Use one step for one model action array

step = await computer.step(
    [
        {"type": "move", "x": 320, "y": 240},
        {"type": "click", "x": 320, "y": 240, "button": "left"},
    ],
    continue_on_error=False,
)

actions = step.actions
screenshot = step.screenshot

A successful return means:

• the complete action tree validated before mutation;
• actions ran once and in order;
• native input synchronized before capture;
• the screenshot passed the same integrity checks as screenshots.full();
• no SDK mutation interleaved between the batch and capture.

The screenshot is immediate. Your application decides when it has finished handling the input.

Choose failure behavior

The default stops after the first known action failure. Set continue_on_error=True only when later actions remain safe after that failure.

Known action failures remain in step.actions. Validation, placement, unknown mutation outcome, lost observation, protocol, frame-integrity, lease, and cleanup failures raise typed exceptions.

The SDK never replays an action after dispatch may have started. Use the operation receipt and explicit recovery interfaces when a response is lost.

Understand input admission

The daemon uses the normalized-input-work-v1 token policy. It reserves the complete recursive batch cost before mutation. The portable baseline refills 100 tokens per second and allows a 400-token burst.

A batch that exceeds the burst fails before mutation. A transient limit returns 429, retry_after_ms, and Retry-After. The SDK exposes the retry delay on the sanitized error.

Rate limiting protects resources. Application approval remains responsible for high-impact actions.

Keep low-level action-only calls explicit

Use computer.actions.run() when the caller intentionally needs an action result without a trailing screenshot. Keep direct REST and idempotency routes for low-level integrations.