Module runtime 

Available on crate features agents and codeact only.

The step-wise interpreter seam — language-agnostic.

The CodeAct driver does not depend on any concrete interpreter or language. It drives a CodeRuntime: start a script, and on each external-function call decide whether to resume with a value, resume by raising an error, or suspend (serialize the continuation and stop).

Errors: script vs. host

Two error channels, kept deliberately distinct:

• Script errors — anything the model should see and react to (a syntax error, an uncaught exception, a resource-limit cancellation) are RunStep::Raised: an opaque string the runtime renders however its language expects (a Python traceback, a JS stack, a shell error). The framework never inspects them; they are fed back to the model verbatim and the run continues. Returning Ok(RunStep::Raised(..)) is always the right move for a model mistake — including a parse/compile failure.
• Host failures — genuine interpreter/host breakage that should abort the run (snapshot (de)serialization failure, an internal interpreter error) are RuntimeError.

When in doubt: if the model could fix it by writing different code, it is a RunStep::Raised, not a RuntimeError.

Async note

Advancing the interpreter (resume) is synchronous and fast. Tool execution (which produces the value passed to resume) is async and happens in the driver between steps, so this trait stays synchronous.

Sequential by design

The seam is a single continuation: RunStep::Call surfaces exactly one pending call, and PendingCall::resume consumes it and yields the next single step. Tool execution is therefore strictly sequential, even if the script’s language supports async/threads — a concurrency-capable runtime must serialize script-level parallelism at the call boundary.

This is deliberate: durability rests on snapshotting one continuation at one call boundary (see PendingCall::dump). Multiple in-flight calls would force a checkpoint to capture partial completion (e.g. a long-running tool inside an asyncio.gather alongside two finished tools), which has no clean suspend/resume semantics. Concurrent host dispatch would require a different seam (e.g. a multi-call step) and is intentionally out of scope.

Structs

RuntimeCapabilities

What a CodeRuntime reports about itself.

Enums

ResumeWith

How to resume a paused external-function call.

RunStep

The result of advancing the interpreter to its next host-relevant stop.

RuntimeError

A host-level failure of the runtime itself (not a script-level error).

Traits

CodeRuntime

A step-wise, language-agnostic code interpreter capable of suspend/resume at call boundaries.

PendingCall

A paused external-function call awaiting a result.

Functions

bind_call_args

Bind a call’s positional and keyword arguments onto a tool’s parameters, producing the single JSON object a Tool expects.

default_tool_catalog

A generic, language-neutral tool listing.