Crate roba_types 

roba’s stable machine contract, as a dependency-light library.

roba is meant to be consumed as a subprocess whose --json output and exit code are a stable ABI. This crate is that ABI, extracted so a downstream harness can deserialize against it and branch on the exit code without depending on the whole roba binary (tokio, clap, termimad, …).

Two pieces:

• Exit codes (EXIT_FAILURE .. EXIT_MAX_BUDGET) – the full map the binary returns. The roba binary references these same constants, so the crate and the binary cannot disagree.
• --json envelopes (SuccessEnvelope, VersionedResult, ErrorEnvelope) – the uniform { version, result[, refusal] } / { version, error } shapes. Each is generic over the payload and derives both Serialize (roba serializes a borrow, no clone) and Deserialize (a consumer deserializes owned), so there is one type per shape and no drift between producer and consumer.

The result payload is claude’s own QueryResult, re-exported here. This crate pulls claude-wrapper with default-features = false, features = ["json"], so it carries serde but no async runtime.

Structs

ErrorBody

The failure detail inside an ErrorEnvelope.

ErrorEnvelope

The --json failure envelope, emitted on stderr: { version, error }.

QueryResult

claude’s result payload – the shape inside a success envelope’s result. Re-exported (not mirrored) so it cannot drift from claude’s contract. Result from a query with --output-format json.

SuccessEnvelope

The --json success envelope for a prompt run: { version, result, refusal }. result holds a QueryResult; refusal is true when the response looked like a refusal, so a consumer can branch on “got an answer” vs “got refused” without parsing the body.

VersionedResult

The --json success envelope for the read-only management commands (cost, history, last, doctor, worktree list, …): { version, result }, without the prompt-run-only refusal flag. Generic over the payload T, which differs per command.

Constants

EXIT_AUTH

Authentication failure (claude is not logged in / the key is bad).

EXIT_BUDGET

The wrapper’s own BudgetTracker ceiling was hit (distinct from claude’s --max-budget-usd CLI cap, which is EXIT_MAX_BUDGET).

EXIT_FAILURE

Generic failure – a claude run failed for a reason with no more specific code, or roba itself errored.

EXIT_MAX_BUDGET

The --max-budget-usd CLI spend cap was hit. Recoverable, like EXIT_MAX_TURNS: a guardrail tripped mid-run, not a defect.

EXIT_MAX_TURNS

The --max-turns cap was hit. Recoverable: the run is usually complete and just needs its lifecycle finished (gates + commit), so a caller can tell this apart from a hard failure and resume.

EXIT_TIMEOUT

The run exceeded its wall-clock --timeout.

EXIT_UNUSABLE_RESULT

A run produced no usable result (empty / is_error). Emitted by the binary directly (never as an error envelope); the reliable machine signal is this code, not stderr.

VERSION

The current --json ABI version. Every envelope carries it as the first field a consumer should check before inspecting anything else.