Async Runtime#

OpenRath v1.2 adds an internal async runtime for model calls, tool dispatch, and persistence. The public API is still synchronous: users call agent(session) or run_session_loop(...) and receive a Session.

Public Boundary#

Surface	Contract
`rath._async`	Private implementation detail; do not import it in user code.
`run_session_loop(...)`	Synchronous public function.
returned `Session`	May be lazy internally, but exposes stable identity, lineage, and sandbox ownership immediately.
`chunk_table` / `cumulative_usage`	Reading either property synchronizes pending async work.
`Session.synchronize()`	Explicit wait point for pending work.

Lazy Session#

Lazy output sessions let OpenRath return a session object before every internal append is fully materialized. This keeps lineage and ownership composable while allowing background work to finish safely.

Read	Behavior
`id`, `parent_session_ids`, `lineage_kind`	Eager metadata.
`sandbox`, `sandbox_backend`	Eager ownership and placement.
`chunk_table`	Waits for pending loop work.
`cumulative_usage`	Waits, then returns accumulated usage.

Parallel Tool Dispatch#

Tools expose a concurrency key through FlowToolCall.resource_key(arguments).

Key relationship	Scheduler behavior
same key	Run serially.
distinct keys	May run concurrently.
default unsafe tool	Uses `("global",)`, so it serializes with other unsafe calls.
`parallel_safe=True`	Default key becomes `("safe", tool.name)`.

This keeps the model transcript deterministic: tool result rows are appended in the original tool-call order even if execution finishes out of order.

Persistence And Crash Detection#

Async persistence writes the same JSONL session format as the synchronous path. During in-flight writes it also creates a .__partial__ marker; a clean trailer removes the marker. Listing or loading persisted sessions can therefore report an interrupted run without guessing from file timestamps.

Failure Semantics#

Failure	User-visible behavior
tool exception	Written as structured JSON `tool_result` and sent back to the model.
invalid tool args	Written as `invalid_tool_arguments`.
unknown tool	Written as `unknown_tool`.
streaming unsupported by client	Raises `TypeError` before registering the loop output.
lazy work failed	Raised when synchronizing the session.

Stability Note#

Document only these behavior boundaries. rath._async names, task classes, writer internals, and event-loop choices are private and may change across minor releases.

← Developer Notes