Runtime

The runtime loop. Constructed with a Graph, an optional set of behaviors, an optional LLM provider, an optional budget, and an optional store. Drives goal runs to completion and persists state through the attached store.

For the conceptual model, see concepts/graph and concepts/behaviors.

status(recent=20)

Frozen snapshot of the runtime. CONTRACT v0.8 #11.

Cheap to call. No graph traversal beyond a tail-slice of the event log. Returns immutable data; mutating any field raises.

recent controls the length of the recent_events tail. The CLI's inspect --tail N passes through.

load_pack(pack, settings=None)

Load a pack into the runtime.

Returns True on first load, False if the same (name, version) was already loaded (CONTRACT v0.9 #6 idempotency). Raises PackVersionConflictError for name-match-version-mismatch and PackConflictError for any contributor name collision. Pre-mutation: a failed load leaves the runtime exactly as it was.

loaded_packs()

List of currently-loaded packs.

get_behavior(name)

Look up a registered behavior by canonical or short name.

Short names resolve when unambiguous (load-time conflict check guarantees this invariant). Raises LookupError if not found or ValueError if ambiguous. CONTRACT v0.9 #8.

get_tool(name)

Look up a registered tool by canonical or short name.

Same resolution rule as get_behavior. CONTRACT v0.9 #8 / #9.

pending_approvals()

List of currently-pending approvals (in creation order).

approve(approval_id, approved_by=None)

Materialize a pending approval. Returns the new object id.

Raises LookupError if approval_id is not pending. Emits an approval.granted event followed by the deferred object.created.

save_state(path=None)

Persist the event log.

• With a store already attached: flush (no path needed). If path is given it must match the attached store's path.
• Without a store: late-bind a SQLite store at path and append all in-memory events to it (CONTRACT v0.5 #5). Returns the path the events were written to.

load(path, run_id=None, *, behaviors=None, frame=None, policy=None, budget=None, seed=0, replay_strict=False, llm_provider=None, replay_llm_cache=False, tools=None, replay_tool_cache=False, replay_reinvoke_deterministic=False, metrics=None) classmethod

Open path, choose a run, replay its events, return a Runtime wired to continue from where the log left off.

If run_id is None, loads the most recently appended-to run (CONTRACT v0.5 #6).

replay_strict=True re-fires behaviors from the recorded seed events and compares the resulting event-type stream (id, type) to the log. KNOWN LIMITATION (v0.5): payload-only drift is not detected; see CONTRACT v0.5 #7. Tightens in v0.6 with LLMs.

v0.8: path accepts a URL (sqlite:///... or postgres://...) in addition to a bare SQLite path. Backward-compatible.

fork(at_event, label=None, *, behaviors=None, llm_provider=None, replay_llm_cache=False, tools=None, replay_tool_cache=False, replay_reinvoke_deterministic=False)

Branch this run at at_event into an independent new run.

Requires a SQLite store. Copies events from the parent's log up to and including at_event into a fresh run_id, replays them into a new Graph, then returns a Runtime that operates on that Graph. Forks-of-forks work the same way (CONTRACT v0.5 #9).

cost_remaining(prospective_cost)

Would prospective_cost push us past the ceiling? Returns True if it's safe to spend, False if it would exceed.

Per-graph monotonic ID generator. Not thread-safe (single-threaded loop).

reseed_from_events(events)

Set counters past the highest id seen in events.

Used after replay so subsequent object()/event()/... continue monotonically from where the loaded log ended. Forks call this too, which is why two forks at the same point produce IDs that diverge identically (decision #12 — fine because the IDs live in different runs).

Clocks

Real wall-clock UTC. ISO 8601 second precision, Z suffix.

Bases: Clock

Always returns the same timestamp. For tests and snapshots.

Bases: Clock

Monotonically advances by step seconds on every call. For tests that care about ordering but don't want wall-clock noise.

Logging + registry helpers

Configure the activegraph logger hierarchy.

Idempotent: repeated calls replace the existing handler rather than stacking. Returns the activegraph root logger.

Parameters:

Name	Type	Description	Default
level	str | int	numeric or string level name.	'INFO'
json_output	bool	True for the documented JSON-line format; False for the stdlib default (one human-readable line).	True
stream	Any	where to write. Defaults to stderr (the logging default).	None
payload_redactor	Optional[Callable[[dict], dict]]	optional callable(dict) -> dict applied to any payload before it's added to a log record's extra fields.	None