Runtime

The current tool context, ids and loop-local state. Concepts: Runtime.

Runtime helpers: sync facade, long-lived loop, per-loop values, the current context and ids.

LoopLocal

Bases: Generic[T]

Lazily creates one factory() value per running event loop.

Loop-bound objects (httpx/redis clients, asyncio.Lock, Semaphore, Event) break when reused from another loop, and every run_sync call runs a new loop. run_sync closes the values before its loop ends; hosts that run their own loops should await LoopLocal.aclose_all() before closing them. Values of loops closed without that are dropped (not closed) on the next get().

aclose() async

Forget this loop's value and close it with close (if given).

Raises:

Type	Description
ToolUsageError	called outside a running event loop.

aclose_all() async classmethod

Close every LoopLocal value bound to the running loop; failures are logged.

get()

The value for the running loop, created on first use.

Raises:

Type	Description
ToolUsageError	called outside a running event loop.

LoopRunner

Runs async work from sync code on one event loop that lives as long as the process.

The loop starts in a daemon thread on the first run(). LoopLocal values (httpx or Redis clients) stay warm across calls. A forked child starts its own loop; close(), a with block or interpreter exit closes the LoopLocal values and stops the loop.

closed property

True once close() has begun.

running property

True while the loop thread is alive.

close(timeout=CLOSE_TIMEOUT_S)

Let in-flight work finish for timeout s, cancel the rest, close LoopLocal values and stop the loop; safe to call twice.

Raises:

Type	Description
ToolUsageError	called from the runner's own loop, or a bad timeout.

run(work, *, timeout=None)

Run work on the runner's loop and block this thread until it finishes.

Parameters:

Name	Type	Description	Default
work	Awaitable[T] | Callable[[], Awaitable[T]]	An awaitable, or a zero-argument callable returning one (called in the loop).	required
timeout	float | None	Seconds before the work is cancelled. The caller also stops waiting CALLER_GRACE_S later, even if the work blocks the loop.	None

Raises:

Type	Description
TimeoutError	the work ran past timeout.
ToolUsageError	bad work or timeout, the runner is closed (or closed while the work ran), or run() was called from the runner's own loop.

current_context()

The context set by the innermost use_context, or None.

new_id(prefix='')

prefix + a random uuid4 hex.

use_context(ctx)

Make ctx current inside the block; child tasks read it, writes never flow back up.

Also exported here, documented under the canonical path: run_sync.