Understand RunContext

What a RunContext owns

RunContext is the execution envelope for one causal run tree. It carries stable identity, parent–child lineage, cancellation, deadline, shared budget accounting, capabilities, metadata, and the event journal.

It is not chat history and it is not global application state. Create a root context at an ingress boundary such as an HTTP request, job, or workflow task.

Create a root run

Start with explicit limits and no authority, then grant only what this run needs.

use runifold::{Budget, BudgetTracker, CapabilitySet, RunContext};
 
let budget = Budget {
    turns: Some(8),
    tool_calls: Some(4),
    ..Budget::default()
};
let run = RunContext::root(
    BudgetTracker::new(budget),
    CapabilitySet::new(),
);

The ergonomic prompt APIs create a default context. Move to an explicit context when policy or accounting matters.

Child runs

Tools, child Agents, and workflow steps derive child contexts from the parent. Children share cancellation and accounting while receiving their own identity and only the authority deliberately delegated to them.

This makes a request reconstructable as a tree and prevents a helper from gaining permissions simply because its caller had them.

Journaling

The journal records semantic lifecycle events: start, usage, callable boundaries, cancellation, failure, and completion. Use it for audit and recovery; use OpenTelemetry for operational traces and metrics.

Attach tenant and request identifiers as low-cardinality metadata. Never place API keys or raw secrets in metadata, events, or error messages.