Runs and events

Legacy contract reference

This page describes the proposed HTTP API contract. Its operations, examples, and limits are not live integration instructions. For current invite-led access, start with Getting started.

A run is durable before the server acknowledges it. Default submission returns 202 and Location. Prefer: wait=10 waits up to ten seconds, returning terminal 200 or the same durable 202. It never creates a second execution mode.

Lifecycle

queued → running → succeeded or failed. A write proposal enters requires_action. Cancellation enters cancel_requested; other terminal outcomes include cancelled, expired, interrupted, and outcome_unknown.

outcome_unknown means an external write may have happened. Reconcile it; do not display “cancelled” or rerun it. Historic terminal events and replay responses remain immutable. Reconciliation adds a receipt.

Reconnectable events

Read /runs/{run_id}/events or open /runs/{run_id}/events/stream. Durable event IDs are sequenced within a run. The JSON cursor and SSE Last-Event-ID resume the same history. Deduplicate by run/event ID; do not assume token-by-token streaming. Keep the last returned event ID separately for later polling or SSE resume; a null page cursor means the current history page has no continuation, not that future events cannot arrive.

curl -N "$MYSTRO_SCOPE/runs/run_example/events/stream" \
  -H "Authorization: Bearer $MYSTRO_API_KEY" \
  -H 'Accept: text/event-stream' \
  -H 'Last-Event-ID: evt_example'

Use only a cursor/event ID actually returned for this run. UI disconnects do not cancel execution. Reconnect or poll to recover the outcome; close your stream when a terminal event arrives.

Cancel and recover

POST /runs/{run_id}/cancel requires an idempotency key. Cancellation stops new dispatch and requests runtime interruption. It cannot undo an already accepted tool operation. A pending approval expires after ten minutes and does not retain an idle execution container.

If a cell is restored and admitted content is missing, the run becomes interrupted with a data-loss reason. Mystro retains admission and operation journals to prevent silent recreation or duplicate writes. These are recovery safeguards, not an active-active availability promise.

Separate time budgets

Budget	Proposed maximum	What it includes
Actor request token	5 minutes	Authority to make new user API requests
Start deadline	5 minutes	Waiting for initial execution to start
Active execution	5 minutes	Running agent work; approval waits do not occupy an idle container
One human approval	10 minutes	Review of the exact operation/input/destination/revision
Durable run authorization	15 minutes	Total wall-clock time from admission, including queue and approval waits

The earliest applicable bound wins. A fresh actor request token does not renew an existing run's execution authorization. A revoked user or parent key is checked again before dispatch even if the original run authorization has time remaining.