ADR-0010: Asynchrony through the event loop and coroutines

• Status: Accepted
• Date: 2026-06-24
• Deciders: jka
• Decision: D10

Context

Several operations take time: streaming model output, running git or other commands, and waiting on the network. Tcl is single-threaded by default, and the UI must never freeze while such work runs.

Decision

Long operations use Tcl's event loop: fileevent for channel readiness and coroutines (Tcl 8.6+) to keep sequential logic readable. rio does not use threads.

Examples in the code base: the agent loop runs each turn in a coroutine that yields at the approval gate and while waiting for a provider (ADR-0026, ADR-0104); command execution for the agent is asynchronous with a timer-driven timeout (ADR-0083); the GUI reads the core channel with a fileevent reader (ADR-0030).

Consequences

• Streaming code reads as a straight sequence rather than as callbacks.
• Anything that blocks the interpreter (a synchronous exec, a synchronous HTTP fetch) blocks every client of that core. Such calls must stay short or be made asynchronous; the agent's command tool had to become asynchronous for exactly this reason.
• Nested event loops need care. vwait inside a fileevent handler, or starting a core call from inside another call's round trip, causes re-entrancy bugs; several later decisions defer work to idle or timer callbacks for this reason.