Execution Runtime
=================

Narrative view of **Execution**, **Thread**, **Run**, **Checkpoint**, and
**Interruption**. For field-level detail see :doc:`../../framework/agency/models`.

Why split intent from attempts
------------------------------

Agency separates:

* **what we meant to do** (Execution),
* **the continuing conversation / graph timeline** (Thread),
* **one shot at advancing that timeline** (Run).

That split supports audit trails, retries, long pauses (HITL), and debugging
without rewriting history.

Relationships
-------------

::

   Execution  (user + agent + mission, overall status/result)
      │
      └── Thread*  (optional FK; ad-hoc threads may omit Execution)
             │
             ├── Run*
             │     └── Checkpoint*
             │            └── Interruption?  (HITL pause at a checkpoint)
             └── …

Statuses (see models for the full ``TextChoices`` set) include
``starting`` / ``running`` / ``success`` / ``interrupted`` / ``error``, plus
others such as ``cancelled``, ``timeout``, and on Run also ``pending`` /
``resuming``.

Case: normal success
--------------------

::

   Execution
   └── Thread
       └── Run #1 → SUCCESS

One attempt completed. Execution result is stored when ``Agent.execute``
finishes without ``__interrupt__``.

Case: error / retry
-------------------

::

   Execution
   └── Thread
       ├── Run #1 → ERROR
       └── Run #2 → SUCCESS

Each Run keeps its own error payload / outcome. A later Run is a new technical
attempt on the same Thread (same ``thread_id``), not an edit of Run #1.

Case: human-in-the-loop
-----------------------

::

   Execution
   └── Thread
       ├── Run #1 → INTERRUPTED
       └── Run #2 → SUCCESS

Run #1 remains ``interrupted``. Resume creates Run #2 with
``Command(resume=…)`` from the answered ``Interruption``. Tutorial:
:doc:`../../tutorials/human-in-the-loop`.

Design payoffs
--------------

* **Audit** — each attempt is a row; interrupted attempts stay interrupted.
* **Observability** — Monitor events and checkpoints attach to Runs.
* **Retries** — new Run, same Thread; prior failures remain inspectable.
* **Debugging** — inspect checkpoint / messages for a specific Run.
* **Long processes** — HITL can wait hours; workers are not held open.

Inspection today
----------------

* REST: ``GET /api/execution/<uuid>/`` (nested threads / runs / interruptions).
* No dedicated public REST for Thread or Run alone.
* Django admin for deep inspection.

See also: :doc:`agent`, :doc:`celery`.