Rental lifecycle and retries

Track the rental ID returned by a reservation. The normal path is:

RESERVED → STARTING → RUNNING → STOPPING → STOPPED

Failures and interruptions can end work without following every normal transition. Treat the server’s state and reason as authoritative, not a timer in your client.

What each stage means

• RESERVED: the reservation has been accepted and budget held. This is not verified execution readiness.
• STARTING: the workload is being prepared. Model loading and readiness checks can take time.
• RUNNING: readiness has been verified and runtime metering has started.
• STOPPING: shutdown has been requested or triggered. Continue observing until a terminal state.
• STOPPED: execution has ended. Any result-retrieval access is read-only and time-limited.
• FAILED: inspect the reason. An unready start has no runtime charge; use the receipt to inspect the actual outcome of a rental that had already run.

Make reservation retries deliberate

Generate and persist an Idempotency-Key UUID before POST /api/v1/jobs. Keep the exact request body with it. On a network timeout, retry that same reservation request with the same key, or inspect your existing rentals first. Do not generate a new key merely because the response was lost.

A reused key with a different request is not a new operation; expect an idempotency conflict. A fresh quote is also not a replay of the old quote: every quote call creates a new record.

MCP create_rental quotes and reserves in one tool call. Save the returned idempotency_key. If a previous attempt might have succeeded, use list_rentals before retrying: its new quote step may fail because the machine is already reserved even though the earlier reservation succeeded.

End or extend the work

Save results, then request POST /api/v1/jobs/{id}/stop with a reason and a stable idempotency key. Repeated stopping is harmless; it is not permission to ignore the response state.

An extension explicitly adds funded budget and a new duration limit using expected job and budget versions. A stale-version response requires a fresh read, not a blind overwrite. Increasing a budget is a new spending decision and needs the operator’s authorization.

Finally, read the receipt. A submitted stop request, browser tab closure, or disconnected client is not by itself evidence that work has ended.